Getting started overview

Euskalmet provides public access to weather data and forecasts specifically for the Basque Country region of Spain. This guide details the steps required to gain access to the Euskalmet API, acquire the necessary credentials, and execute a foundational request to retrieve weather information. The process involves navigating the Euskadi Open Data portal, registering for an API key, and understanding the basic structure of an API call. Euskalmet's API is distributed through the Euskadi Open Data portal, which serves as the central hub for documentation and access management.

The Euskalmet API is designed for developers and researchers who need localized weather information, offering data points such as temperature, precipitation, wind speed, and atmospheric pressure. While the primary documentation is in Spanish, the API itself uses standard HTTP/S protocols and JSON responses, making it accessible to a broader technical audience. Access to the API is provided without charge, but registration and an API key are mandatory for all requests.

This page focuses on the technical procedures for initial setup and interaction, assuming familiarity with general API concepts like HTTP methods and API keys. Successful completion of these steps will enable you to retrieve current weather conditions or forecasts for specific locations within the Basque Country.

Quick reference steps

The following table summarizes the essential steps to get started with the Euskalmet API:

Step What to Do Where
1. Register Create an account on the Euskadi Open Data portal. Euskadi Open Data Portal registration
2. Request API Key Subscribe to the Euskalmet API and generate your API key. Within your Euskadi Open Data account dashboard
3. Review Docs Familiarize yourself with API endpoints and parameters. Euskalmet API documentation
4. Make Request Construct and execute your first API call using your key. Your preferred development environment (e.g., cURL, Postman)

Create an account and get keys

To begin using the Euskalmet API, you must first register an account on the Euskadi Open Data portal. This portal manages access to various public datasets, including Euskalmet's weather information.

  1. Navigate to the Euskadi Open Data Portal: Open your web browser and go to the Euskalmet API page on the Euskadi Open Data portal.
  2. Register for an Account: Look for a "Registrarse" (Register) or "Crear cuenta" (Create account) option, typically found in the header or sidebar. Follow the prompts to provide your email address, create a password, and agree to the terms of service. You may need to verify your email address through a link sent to your inbox.
  3. Log In: Once registered and verified, log in to your new account using your credentials.
  4. Subscribe to the Euskalmet API: After logging in, return to the Euskalmet API product page. There should be an option to "Suscribirse" (Subscribe) or "Obtener acceso" (Get access) to the API. Click this option.
  5. Generate API Key: Upon successful subscription, the portal will typically generate an API key for you. This key is a unique string of characters that authenticates your requests to the Euskalmet API. Copy this key immediately and store it securely, as it will be required for all subsequent API calls. The platform may display it only once.

The API key acts as a credential, similar to a password for API requests. It is crucial to protect your API key to prevent unauthorized usage, which could lead to rate limit issues or other service interruptions. Best practices for API key management include storing them as environment variables rather than hardcoding them directly into your application's source code, as recommended in general API security guidelines like those from Google Developers API key best practices.

Your first request

After obtaining your API key, you can make your first request to the Euskalmet API. This example demonstrates how to retrieve current weather conditions for a specific location within the Basque Country, using a common tool like cURL. The Euskalmet API uses standard REST principles, with endpoints for various data types.

API endpoint structure

The base URL for the Euskalmet API is typically https://opendata.euskadi.eus/api/euskalmet/. Specific endpoints are appended to this base URL. For instance, to get a forecast, you might use an endpoint like /forecast/locations/{locationId}.

Example request: Current conditions

To make a request, you will need:

  • Your API key (YOUR_API_KEY)
  • An endpoint. For demonstration, we'll use a hypothetical endpoint for current weather, often found in the API documentation. The specific endpoint details, including required parameters, are available on the Euskalmet API documentation page under the "Documentación" or "Especificación OpenAPI" section.
  • A location identifier, if required by the chosen endpoint. Euskalmet typically uses geographical codes or names for locations within the Basque Country.

Assuming an endpoint for current observations at a specific station (e.g., "Vitoria-Gasteiz" represented by an ID):

curl -X GET \
  "https://opendata.euskadi.eus/api/euskalmet/meteorological/weather/observations/current/station/{station_id}" \
  -H "Accept: application/json" \
  -H "X-API-KEY: YOUR_API_KEY"

Note: Replace {station_id} with an actual station identifier from the Euskalmet documentation (e.g., '100000001' for a specific reporting station in Vitoria-Gasteiz). You must also replace YOUR_API_KEY with the key you obtained during registration. The exact endpoints and parameters will be detailed in the official Euskalmet API documentation.

A successful response will typically be a JSON object containing weather data. For example:

{
  "timestamp": "2026-05-29T10:30:00Z",
  "stationId": "100000001",
  "stationName": "Vitoria-Gasteiz",
  "temperature": {
    "value": 15.2,
    "unit": "C"
  },
  "humidity": {
    "value": 78,
    "unit": "%"
  },
  "windSpeed": {
    "value": 12,
    "unit": "km/h"
  },
  "description": "Partly cloudy"
}

This JSON structure indicates that the API is responding with current meteorological observations for the specified station, including temperature, humidity, and wind speed. The precise fields and their values will vary based on the specific endpoint queried and the data available.

Common next steps

Once you have successfully made your first API request, consider these common next steps to further integrate Euskalmet data into your applications:

  1. Explore Additional Endpoints: The Euskalmet API offers various endpoints beyond current observations, including short-term and long-term forecasts, climatological data, and specific warnings. Consult the official documentation to understand the full range of available data and how to access it. This often includes endpoints for specific municipalities or regions within the Basque Country, as well as different time horizons for forecasts.
  2. Implement Error Handling: Integrate robust error handling into your application. The API will return specific HTTP status codes (e.g., 400 for bad request, 401 for unauthorized, 404 for not found, 429 for too many requests) and error messages in the JSON response. Your application should be able to gracefully manage these situations to provide a stable user experience. Familiarize yourself with HTTP response status codes to properly interpret API responses.
  3. Manage API Key Securely: Ensure your API key is not exposed in client-side code, public repositories, or unsecured environments. Utilize environment variables, secret management services, or server-side proxies to protect your credentials.
  4. Understand Rate Limits: Review the API documentation for information on rate limits. Euskalmet, as a public service, may have usage policies to ensure fair access for all users. Plan your requests to stay within these limits to avoid temporary blocking of your API key.
  5. Parse and Display Data: Develop logic to parse the JSON responses and integrate the weather data into your application's user interface or backend processes. Consider how to format and visualize the data for clarity and usability, especially for time-series data like forecasts.
  6. Localized Data Handling: Given Euskalmet's regional focus, consider how to best handle localized data, including potential language differences (e.g., translating weather descriptions) and unit conversions if your application requires it (e.g., converting Celsius to Fahrenheit).
  7. Stay Updated: Periodically check the Euskadi Open Data portal or the Euskalmet website for API updates, new features, or changes in data availability.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps:

  • Check API Key: Double-check that your API key is correctly copied and included in the X-API-KEY header. Even a single character error will result in an authentication failure (HTTP 401 Unauthorized). Ensure there are no leading or trailing spaces.
  • Verify Endpoint and Parameters: Confirm that the API endpoint URL is correct and that all required parameters (e.g., station_id, date) are present and correctly formatted according to the Euskalmet API documentation. Typos in endpoint paths or parameter names are frequent causes of HTTP 404 Not Found or 400 Bad Request errors.
  • Review HTTP Headers: Ensure you are sending the correct headers, especially Accept: application/json if you expect a JSON response. Missing or incorrect headers can lead to errors or unexpected response formats.
  • Internet Connectivity: Confirm your development environment has a stable internet connection and is not blocked by a firewall or proxy.
  • Rate Limiting: While less likely on a first call, if you've rapidly made multiple attempts, you might hit a rate limit (HTTP 429 Too Many Requests). Wait a few minutes before retrying.
  • Consult Documentation: Re-read the relevant sections of the Euskalmet API documentation carefully. Pay close attention to examples and descriptions of required fields. The documentation is the definitive source for API behavior.
  • Examine Response Body: If you receive an error status code (e.g., 400, 401, 404), the API response body often contains a JSON object with a detailed error message that can pinpoint the problem. For example, a 400 Bad Request might include a message indicating which parameter is invalid.
  • Use a Tool like Postman: Tools like Postman or Insomnia provide a graphical interface for constructing and testing API requests, making it easier to manage headers, parameters, and view responses compared to raw cURL commands. This can help isolate whether the issue is with your code or the request structure itself.