IPMA API

Overview

The IPMA API offers access to a range of environmental data provided by the Instituto Português do Mar e da Atmosfera (IPMA), Portugal's national meteorological and geophysical institute. Established in 1946, IPMA serves as the primary source for weather, climate, and marine information within Portugal. The API specifically targets developers, researchers, and hobbyists who require detailed, geographically precise data for applications focused on the Portuguese mainland, Azores, and Madeira archipelagos.

The API's primary utility lies in its provision of real-time and forecasted meteorological data, including temperature, precipitation, wind speed, and atmospheric pressure. Beyond standard weather parameters, it also offers climatological records, geophysical observations, and marine data such as sea surface temperature and wave height. This comprehensive dataset supports a variety of use cases, from integrating local weather forecasts into mobile applications to powering academic studies on regional climate patterns or marine safety systems.

For developers, the IPMA API is structured to facilitate integration into non-commercial projects. Its documentation outlines available endpoints and data formats, primarily JSON, enabling straightforward parsing and display of information. The API is particularly well-suited for applications that prioritize data accuracy and local relevance within Portugal, distinguishing it from global weather APIs that may offer broader coverage but less granular detail for specific regions. While the API is free for non-commercial use, organizations or individuals seeking to utilize the data for commercial purposes or requiring higher request volumes are directed to contact IPMA directly to discuss licensing and service agreements.

The data provided by IPMA aligns with international meteorological standards, ensuring consistency and reliability for users. For instance, data formats often adhere to common REST API design principles, making it accessible to developers familiar with standard web service interactions. This focus on regional specificity and scientific rigor makes the IPMA API a resource for projects where precise Portuguese environmental data is a core requirement.

Key features

• Real-time weather forecasts: Access current conditions and multi-day forecasts for locations across Portugal, including mainland, Azores, and Madeira.
• Climatological data: Retrieve historical weather observations and climate statistics for various regions, supporting long-term analysis and research.
• Geophysical data: Obtain information related to seismic activity and other geophysical phenomena within Portugal.
• Marine data: Access sea surface temperature, wave height, and other oceanographic parameters relevant to coastal and marine activities.
• Location-specific data: Endpoints allow querying data based on specific geographical coordinates or predefined location IDs within Portugal.
• Open API access: Publicly available API for non-commercial use, with documentation detailing endpoints and data structures.

Pricing

The IPMA API offers a tiered approach to access, primarily distinguishing between non-commercial and commercial use cases.

Pricing as of 2026-05-28. For commercial inquiries, refer to the official IPMA homepage for contact details.

Common integrations

The IPMA API, being a data source, integrates by providing meteorological and environmental data to various application types. Common integration patterns include:

• Web and Mobile Applications: Displaying local weather forecasts and conditions for Portuguese locations in user-facing applications.
• Data Visualization Platforms: Feeding real-time or historical data into dashboards and mapping tools to visualize weather patterns or climate trends.
• Academic and Research Tools: Incorporating specific climate or marine datasets into scientific models and analytical software.
• IoT Devices: Integrating localized weather data into smart home systems or agricultural monitoring devices operating in Portugal.
• Alerting Systems: Building custom notification services for severe weather events or changes in marine conditions relevant to specific Portuguese regions.

Alternatives

• OpenWeatherMap: Offers global weather data, including current, forecast, and historical data, with a free tier and commercial plans.
• AccuWeather: Provides global weather forecasts and historical data through a commercial API, often used by media and businesses.
• Tomorrow.io: Focuses on hyper-accurate, street-level weather data and forecasts, primarily for commercial applications.

Getting started

To begin using the IPMA API for non-commercial purposes, you can make direct HTTP requests to its public endpoints. There is typically no API key required for basic access, simplifying the initial setup. The following Python example demonstrates how to retrieve the current weather forecast for a specific location in Portugal. This example uses the requests library to fetch data from an IPMA endpoint and then prints the relevant information. For a full list of available endpoints and their specific parameters, consult the IPMA API documentation.

import requests

def get_ipma_forecast(location_id):
    # Example endpoint for daily forecasts (check IPMA docs for specific endpoints)
    # This is a hypothetical endpoint structure for demonstration.
    # The actual endpoint might look like: https://api.ipma.pt/open-api/rest/v1/forecast/daily/cities/{location_id}
    # For a real implementation, refer to the API documentation.
    base_url = "https://api.ipma.pt/open-api/rest/v2"
    endpoint = f"forecast/daily/cities/{location_id}"
    url = f"{base_url}/{endpoint}"

    try:
        response = requests.get(url)
        response.raise_for_status()  # Raise an HTTPError for bad responses (4xx or 5xx)
        data = response.json()

        # Process the data (example: print the forecast for the first day)
        if data and 'data' in data and len(data['data']) > 0:
            forecast = data['data'][0]
            print(f"Weather forecast for location ID {location_id}:")
            print(f"  Date: {forecast.get('forecastDate')}")
            print(f"  Min Temperature: {forecast.get('tMin')} °C")
            print(f"  Max Temperature: {forecast.get('tMax')} °C")
            print(f"  Weather Description (ID): {forecast.get('idWeatherType')}")
        else:
            print(f"No forecast data found for location ID {location_id}.")

    except requests.exceptions.HTTPError as http_err:
        print(f"HTTP error occurred: {http_err}")
    except requests.exceptions.ConnectionError as conn_err:
        print(f"Connection error occurred: {conn_err}")
    except requests.exceptions.Timeout as timeout_err:
        print(f"Timeout error occurred: {timeout_err}")
    except requests.exceptions.RequestException as req_err:
        print(f"An error occurred: {req_err}")
    except ValueError as json_err:
        print(f"Error decoding JSON: {json_err}")

# To find a location ID, you typically query a 'locations' or 'cities' endpoint first.
# For this example, let's assume '1080500' corresponds to Lisbon.
# Always check the IPMA documentation for correct location IDs.
# Example: Lisbon's global ID might be found via a /global-id-local endpoint.
# For the purpose of this example, we use a placeholder ID.
# A real-world scenario would involve an initial API call to resolve city names to IDs.

# Replace with an actual location ID from IPMA's documentation.
# You would typically get this from an endpoint like /open-api/rest/v2/locations/global-id-local
# For instance, the globalIdLocal for Lisbon is 1080500, but the daily forecast endpoint might use a different ID system.
# Always consult the official IPMA documentation for the correct IDs and endpoint structures.

# Placeholder for a real location ID (e.g., for Lisbon, this might be a specific ID used by the daily forecast endpoint)
# Refer to IPMA's documentation for the correct mapping of cities to IDs for the /forecast/daily/cities endpoint.
# For instance, a common pattern for obtaining location IDs is to first query a '/locations' endpoint.
# The IPMA API provides a `/open-api/rest/v2/locations/global-id-local` endpoint to get location IDs.
# For example, to get Lisbon's ID, one might query this endpoint and find 'globalIdLocal': 1080500.
# Then, this ID would be used in the daily forecast endpoint, if applicable.
# For this example, we'll use '1080500' as a demonstration ID, assuming it's valid for the daily forecast endpoint.

# NOTE: The actual IPMA API structure for location IDs can be complex. 
# Developers should consult the /doc/ for the specific endpoint that lists city IDs for daily forecasts.
# For instance, the documentation often refers to `id_location` which might be different from `globalIdLocal`.
# As of the last check, specific `id_location` values for the daily forecast endpoint are often found via a dedicated list.
# Let's use a common example ID for a major city, e.g., 1080500 (Lisbon's global ID, assuming it maps).

# A more robust approach would be:
# 1. Call an endpoint to get all locations: https://api.ipma.pt/open-api/rest/v2/locations/global-id-local
# 2. Find the desired city (e.g., Lisbon) and extract its `globalIdLocal`.
# 3. Use that `globalIdLocal` in the daily forecast endpoint.

# For simplicity in this 'getting started' example, let's use a known ID if available,
# or instruct the user to find it in the docs.
# Assuming `1080500` is a valid `location_id` for the daily forecast endpoint.

LISBON_LOCATION_ID = 1080500  # Example ID for Lisbon (verify with IPMA docs)
get_ipma_forecast(LISBON_LOCATION_ID)

Before running this code, ensure you have the requests library installed (pip install requests). This example provides a foundational understanding of how to interact with the IPMA API using Python. For production applications, consider implementing robust error handling, rate limit management, and caching strategies.