Aemet Getting Started: API Key & First Request (2026)

Getting started overview

Getting started with the Aemet API involves a sequence of steps designed to provide access to Spain's official meteorological data. The process begins with registration on the Aemet Open Data portal, which is necessary to acquire an API key. This key is a unique identifier that authenticates your application when making requests to the Aemet API endpoints. The API focuses exclusively on Spanish weather information, offering various datasets such as daily forecasts, historical climatological records, and real-time observation data. While the primary documentation is in Spanish, the API structure and example requests are generally clear, facilitating integration for developers. The service is provided free of charge, subject to specific rate limits designed to ensure fair usage across all consumers.

The Aemet API operates on a RESTful architecture, meaning it uses standard HTTP methods (GET, POST, PUT, DELETE) to interact with resources. Data is typically returned in JSON format, a common choice for web APIs due to its human-readability and ease of parsing by machines. Understanding basic REST principles and JSON data structures is beneficial for efficient integration. For developers new to REST APIs, resources like the Mozilla Developer Network's REST glossary provide foundational knowledge.

To summarize the initial setup, the following table outlines the key steps:

Create an account and get keys

Accessing the Aemet API requires a valid API key, which is obtained through a registration process on the official Aemet Open Data portal. This key serves as your authentication credential for all API interactions. Without it, requests will be rejected, typically with an HTTP 401 Unauthorized status code.

To initiate the process:

1. Navigate to the Aemet Open Data Portal: Go to the Aemet API documentation page. This page provides an overview of the API and links to the registration area.
2. Locate Registration: Look for a section or link related to 'Registro' (Registration) or 'Solicitar API Key' (Request API Key). The portal is primarily in Spanish, so familiarity with these terms or using a browser's translation feature can be helpful.
3. Complete the Registration Form: You will typically be asked for personal details such as your name, email address, and possibly information about your intended use of the API. Providing accurate information is important for compliance and communication.
4. Verify Email (if required): Some registration processes include an email verification step. Check your inbox for a confirmation email from Aemet and follow the instructions to activate your account.
5. Obtain Your API Key: Once registered and logged in, your API key should be displayed in your user profile or a dedicated 'API Keys' section. The key is a long alphanumeric string. It is crucial to treat this key as sensitive information, similar to a password. Do not hardcode it directly into client-side code that could be publicly exposed, and avoid sharing it unnecessarily.

The Aemet API key is typically passed in the api_key query parameter or an api-key HTTP header with each request. The documentation will specify the exact method. For security best practices, especially when dealing with server-side applications, consider storing your API key as an environment variable rather than directly in your source code. This practice helps prevent accidental exposure and simplifies key rotation.

Your first request

After obtaining your API key, the next step is to make your first successful request to an Aemet API endpoint. This validates your key and ensures your setup is correct. A common starting point is to fetch a list of available municipalities or a general forecast, as these endpoints often require minimal parameters beyond the API key.

Let's consider an example of fetching the list of available municipalities for which Aemet provides weather data. This is often an initial step to then query specific forecasts.

The endpoint for this might look something like https://opendata.aemet.es/opendata/api/maestro/municipios. (Always verify the exact current endpoint from the Aemet API documentation.)

You will need to include your API key in the request. Assuming the documentation specifies passing the key as an api_key query parameter:

curl -X GET \
  'https://opendata.aemet.es/opendata/api/maestro/municipios?api_key=YOUR_API_KEY' \
  -H 'Accept: application/json'

Replace YOUR_API_KEY with the actual API key you obtained during registration.

Upon a successful request, the API will typically return a JSON response. For the municipalities endpoint, this response might contain a list of objects, each representing a municipality with its code, name, and other relevant information. For example:

{
  "descripcion": "Municipios de España",
  "datos": "https://opendata.aemet.es/opendata/sh/XXXXXXXX",
  "estado": 200
}

Notice that the initial response often provides a datos field, which is another URL. This is a common pattern in the Aemet API: the first call often returns a URL pointing to the actual data, which you then need to query. This design allows Aemet to serve data efficiently, potentially from cached resources or dynamically generated files.

To get the actual list of municipalities, you would then make a second request to the URL provided in the datos field, again including your API key:

curl -X GET \
  'https://opendata.aemet.es/opendata/sh/XXXXXXXX?api_key=YOUR_API_KEY' \
  -H 'Accept: application/json'

This second request would yield the detailed JSON array of municipalities. This two-step process is important to understand when integrating with Aemet's data. Always check the initial response for a datos URL when expecting specific data.

Common next steps

Once you've successfully made your first API call and understand the two-step data retrieval process, you can proceed with more advanced integration. Here are some common next steps:

1. Explore Other Endpoints: Review the Aemet API documentation to identify other relevant endpoints. These might include daily forecasts (/api/prediccion/especifica/municipio/diaria/), hourly forecasts, historical data, or climate observations. Each endpoint will have specific parameters required, such as municipality codes (codigoine) or date ranges.
2. Implement Error Handling: Integrate robust error handling into your application. The API will return various HTTP status codes (e.g., 400 Bad Request, 401 Unauthorized, 404 Not Found, 429 Too Many Requests) and JSON error messages. Your application should gracefully handle these to provide a stable user experience. For example, a 429 status code indicates you've exceeded the Aemet API rate limits (300 requests per minute, 10 requests per second), and your application should implement a retry mechanism with exponential backoff.
3. Parse and Display Data: Develop code to parse the JSON responses and extract the specific weather data you need. This might involve iterating through arrays, accessing nested objects, and converting data types (e.g., temperatures from Celsius to Fahrenheit if desired). Consider how you will present this data in your application's user interface.
4. Manage Rate Limits: Be mindful of the Aemet API's rate limits. For applications requiring frequent updates, implement caching strategies to store data locally for a period before making new API calls. This reduces the number of requests to the API and helps stay within the allowed limits. For instance, if a forecast for a municipality is updated once every few hours, there's no need to fetch it every minute.
5. Secure Your API Key: For production applications, ensure your API key is stored and used securely. Avoid hardcoding it directly into client-side code. Server-side applications should use environment variables or a secrets management service.
6. Contribute to the Community: If you encounter issues or develop useful code snippets, consider sharing them. While Aemet's community support might be primarily in Spanish, forums or open-source projects can be valuable resources for collective problem-solving.
7. Monitor API Changes: Periodically check the Aemet Open Data portal for announcements regarding API updates, new endpoints, or changes to existing ones. APIs can evolve, and staying informed helps maintain application compatibility.

Troubleshooting the first call

When making your first API call, it's common to encounter issues. Here are some troubleshooting steps for common problems:

• 401 Unauthorized: This status code almost always indicates an issue with your API key.
• Check for typos: Ensure your API key is copied and pasted exactly as provided, with no extra spaces or missing characters.
• Verify key inclusion: Confirm that the API key is included in the request as specified by the Aemet documentation (e.g., as a query parameter api_key or an api-key HTTP header).
• Key activation: Make sure your account registration is complete and the API key has been activated. Sometimes there's a delay or an email verification step required.
• 404 Not Found: This typically means the endpoint URL is incorrect.
• Endpoint URL: Double-check the URL against the Aemet API reference. Endpoints can change or have specific versioning.
• Path parameters: If the endpoint requires path parameters (e.g., a municipality ID), ensure they are correctly formatted and valid.
• 400 Bad Request: This usually points to issues with the request parameters.
• Missing parameters: Verify that all required query parameters (e.g., date, municipality code) are present.
• Incorrect parameter format: Ensure parameters are in the correct format (e.g., dates as 'YYYY-MM-DD', numeric values as integers).
• Invalid values: Check if the values provided for parameters are within the expected range or set of valid options.
• Empty or Unexpected JSON Response: If you receive a 200 OK status but the data is not what you expect.
• Two-step data retrieval: Remember the Aemet API's common pattern of returning a datos URL in the initial response. You often need to make a second request to this URL to get the actual data.
• Data structure: Consult the API documentation for the expected JSON structure of the specific endpoint.
• Connection Issues: If you receive no response or a network error.
• Internet connectivity: Ensure your development environment has a stable internet connection.
• Firewall/Proxy: Check if a firewall or proxy is blocking your outgoing HTTP requests.
• Rate Limit Exceeded (429 Too Many Requests): If you make too many requests within a short period.
• Wait and retry: Respect the rate limits. Wait for a few minutes before trying again.
• Review usage: Analyze your application's request patterns and implement caching or delayed requests to stay within limits.

When troubleshooting, using tools like cURL for command-line testing or Postman/Insomnia for GUI-based API testing can help isolate issues by allowing you to construct and inspect requests and responses outside of your application code.