IPMA Getting Started: Free Portuguese Weather Data (2026)

Getting started overview

The IPMA API provides direct access to real-time and historical weather data, climate information, geophysical observations, and marine forecasts for Portugal. Unlike many commercial APIs, the IPMA API is primarily designed for public, non-commercial use and does not require an API key for basic access. This simplifies the initial setup process, allowing developers to quickly retrieve data for Portuguese locations.

The API follows a RESTful architecture, returning data in JSON format, which is a common data interchange format for web APIs as defined by W3C. This guide outlines the straightforward steps to make your first data request, focusing on typical meteorological queries like current weather conditions or forecasts for Portuguese cities.

Before proceeding, ensure you understand the terms of use, particularly the non-commercial stipulation for public API access. For commercial applications or higher request volumes, direct contact with IPMA is necessary according to their developer experience notes.

Create an account and get keys

The IPMA API's public access model means that creating an account or obtaining an API key is not required for non-commercial use. Developers can directly access the API endpoints without prior registration.

This approach differs from many commercial APIs, such as Stripe or Twilio, which typically require an account registration, dashboard access, and the generation of API keys (e.g., Stripe API keys, Twilio API keys) for authentication. The IPMA API instead relies on usage policies to govern access.

For operations that fall outside the public, non-commercial scope, such as high-volume requests or commercial applications, the official IPMA documentation advises direct contact. Details for such inquiries would be provided upon contacting them, rather than through an automated sign-up process.

Your first request

To make your first request to the IPMA API, you will typically query an endpoint for a specific location or type of meteorological data. A common starting point is to retrieve the forecast for a Portuguese city. The API uses identifier codes for locations. You can first retrieve a list of available locations and their IDs.

Step 1: Get a list of available locations

The IPMA API provides an endpoint to retrieve a list of all meteorological stations and their associated global ID (globalIdLocal). This ID is crucial for subsequent data requests.

curl -X GET "https://api.ipma.pt/open-api/distrits-islands/forecast/previsions.json"

This request fetches a JSON array containing information about various districts and islands in Portugal, including their globalIdLocal. For example, the entry for Lisbon might look like:

{
  "globalIdLocal": 1110600,
  "local": "Lisboa",
  "idRegiao": 11,
  "idAreaAviso": "LI",
  "latitude": "38.7223",
  "longitude": "-9.1393"
}

Note down the globalIdLocal for the city you wish to query, such as 1110600 for Lisbon.

Step 2: Request daily forecast data for a specific location

Once you have the globalIdLocal, you can request the daily forecast. The endpoint for daily forecasts typically involves the location ID.

curl -X GET "https://api.ipma.pt/open-api/forecast/meteorology/cities/daily/1110600.json"

Replace 1110600 with the globalIdLocal of your chosen city. The API will return a JSON object containing the daily forecast for that location.

Example Response (abbreviated)

{
  "owner": "IPMA",
  "country": "PT",
  "data": [
    {
      "precipitaDesc": "Sem precipitação",
      "tMin": 15.0,
      "tMax": 25.0,
      "predWindDir": "NE",
      "idWeatherType": 1,
      "classWindSpeed": 2,
      "longitude": "-9.1393",
      "latitude": "38.7223",
      "forecastDate": "2026-05-30"
    },
    {
      "precipitaDesc": "Sem precipitação",
      "tMin": 16.0,
      "tMax": 26.0,
      "predWindDir": "NE",
      "idWeatherType": 1,
      "classWindSpeed": 2,
      "longitude": "-9.1393",
      "latitude": "38.7223",
      "forecastDate": "2026-05-31"
    }
  ],
  "globalIdLocal": 1110600,
  "dataUpdate": "2026-05-29T10:00:00"
}

This response includes forecast data points for multiple days, detailing minimum and maximum temperatures (tMin, tMax), precipitation description (precipitaDesc), and other meteorological parameters. The official IPMA API documentation provides a comprehensive list of all data fields and their meanings.

Quick Reference: First IPMA API Call

Common next steps

After successfully making your first request, consider these common next steps to further integrate the IPMA API into your application:

• Explore More Endpoints: The IPMA API offers various endpoints beyond daily forecasts. Investigate options for historical data, hourly forecasts, marine data, or specific geophysical parameters. The full API documentation details all available resources.
• Implement Error Handling: As with any external API, requests can fail due to network issues, invalid parameters, or server-side problems. Implement robust error handling in your code to gracefully manage HTTP status codes (e.g., 404 Not Found, 500 Internal Server Error) and provide informative feedback to users.
• Cache Data: To optimize performance and reduce the load on the IPMA servers, consider caching frequently requested data. Weather data often doesn't change every minute, so storing responses for a set period can be efficient. Be mindful of the API's update frequency when determining cache invalidation strategies.
• Rate Limiting: While IPMA does not explicitly publish rate limits for its public API, it's good practice to implement client-side rate limiting to avoid overwhelming the server. If you anticipate high usage, contact IPMA for guidance on appropriate request volumes.
• Monitor API Status: Keep an eye on the IPMA website or any provided status pages for announcements regarding API maintenance or outages. This helps in diagnosing unexpected issues with your integration.
• Develop for Specific Use Cases: Depending on your project, you might integrate IPMA data with other services, such as mapping APIs (e.g., ArcGIS Geocoding Service) for visualizing weather patterns, or notification services (e.g., Twilio) to send weather alerts.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips for the IPMA API:

• Check Endpoint URL: Double-check that the URL you are using matches the exact endpoint specified in the IPMA API documentation. Typos are a frequent cause of 404 Not Found errors.
• Verify Location ID: Ensure the globalIdLocal you are using for city-specific requests is correct and corresponds to an existing location in the IPMA database. You can re-run the distrits-islands endpoint to confirm the ID.
• Network Connectivity: Confirm that your machine has an active internet connection and that no firewalls or proxies are blocking outgoing HTTP requests to api.ipma.pt.
• HTTP Status Codes: Pay attention to the HTTP status code returned in the response.
• 200 OK: The request was successful.
• 404 Not Found: The requested resource (e.g., an invalid endpoint or location ID) could not be found.
• 5xx Server Error: Indicates a problem on the IPMA server side. These are usually temporary; try again later.
• JSON Parsing Errors: If you receive a successful response (200 OK) but your application struggles to parse the data, ensure you are correctly handling JSON. Malformed JSON or unexpected data structures can cause parsing failures. Use a JSON linter or validator to inspect the raw response.
• Browser vs. cURL: If a cURL command works but your browser or application does not, there might be differences in how headers are sent (though less common for public APIs without keys). Ensure your application client is configured correctly.
• Consult Documentation: The IPMA API documentation is the primary source of truth. Refer to it for specific endpoint requirements, expected parameters, and response structures.