SDKs overview

Software Development Kits (SDKs) and libraries for Euskalmet facilitate interaction with its API for weather prediction and data. These tools encapsulate the API's HTTP requests and response parsing, enabling developers to integrate Euskalmet's meteorological information into their applications without directly managing low-level network communication or JSON parsing. The Euskalmet API primarily provides weather data for the Basque Country region of Spain, offering forecasts, real-time observations, and historical climatological data.

SDKs typically offer a higher-level abstraction than direct API calls, often providing language-specific objects and methods corresponding to API endpoints. This approach can reduce development time and potential errors by handling details such as authentication, request formatting, and error handling. While Euskalmet provides official resources, the open-data nature also encourages community-driven development of additional libraries.

Before using any SDK or library, developers must register for an API key through the Euskadi Open Data portal. This key is essential for authenticating requests and accessing the data. The API access is free for public use, aligning with the Basque Government's open data initiatives.

Official SDKs by language

Euskalmet's primary official support for programmatic access is through its well-documented RESTful API. While a comprehensive suite of language-specific SDKs might not be maintained directly by Euskalmet, the official documentation often provides examples and guidance for interacting with the API using common web development patterns. The focus is on providing clear API specifications, allowing developers to choose their preferred language and tooling.

For direct interaction with REST APIs, many languages offer built-in or widely adopted HTTP client libraries:

  • Python: The requests library is a popular choice for making HTTP requests and handling JSON responses.
  • JavaScript/Node.js: fetch (native in browsers, polyfilled or via node-fetch in Node.js) or axios are commonly used for asynchronous HTTP communication.
  • Java: The java.net.HttpClient (since Java 11) or external libraries like Apache HttpClient are standard for network operations.
  • C#: HttpClient in .NET provides methods for sending HTTP requests and receiving HTTP responses.

These generic HTTP clients form the basis for building custom client libraries or integrating directly with the Euskalmet API. The official documentation serves as the authoritative source for endpoint definitions, required parameters, and expected response structures.

While Euskalmet does not publish a formal table of official SDKs in the traditional sense (e.g., a dedicated Python package maintained by the Euskalmet team), the API's design is compatible with standard web development practices. The following table illustrates how developers typically approach official integration:

Language Common Approach/Package Install Command (Example) Maturity/Status
Python requests library for HTTP calls pip install requests Stable, widely used for API interaction
JavaScript (Node.js) axios or node-fetch for HTTP calls npm install axios Stable, widely used for API interaction
Java java.net.HttpClient (built-in) or Apache HttpClient (Built-in) or Add Maven/Gradle dependency for Apache HttpClient Stable, standard for Java applications
C# (.NET) HttpClient (built-in) (Built-in) Stable, standard for .NET applications

Installation

Since Euskalmet's official approach relies on direct API interaction using standard HTTP client libraries, installation involves setting up these generic tools rather than a specific Euskalmet-branded SDK. The process varies slightly by programming language and environment.

Python

For Python, the requests library is highly recommended for its user-friendly API. You can install it using pip, Python's package installer:

pip install requests

Ensure you have Python and pip installed on your system. You can verify the installation by running pip --version.

JavaScript (Node.js)

In Node.js environments, axios is a popular promise-based HTTP client. Install it using npm, the Node.js package manager:

npm install axios

Alternatively, for a lightweight solution or if working in a browser environment with modern JavaScript, the native fetch API can be used directly without installation. For Node.js, a polyfill like node-fetch might be needed for older Node.js versions or specific use cases:

npm install node-fetch@2 # For Node.js < 18

Make sure you have Node.js and npm installed.

Java

For Java applications, the HttpClient is built into the Java Development Kit (JDK) since Java 11. No separate installation is required. If using older Java versions or a more feature-rich client, Apache HttpClient is a common choice. If using Maven, add the following dependency to your pom.xml:

<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <version>4.5.13</version> <!-- Use the latest stable version -->
</dependency>

For Gradle, add to your build.gradle:

implementation 'org.apache.httpcomponents:httpclient:4.5.13' // Use the latest stable version

Refer to the Apache HttpClient documentation for the latest version and detailed usage.

C# (.NET)

In C# and .NET applications, the HttpClient class is part of the .NET framework and does not require separate installation. It is available by default in modern .NET projects. You can typically find it in the System.Net.Http namespace.

Quickstart example

This example demonstrates how to fetch the current weather forecast for a specific location in the Basque Country using the Euskalmet API with Python's requests library. This assumes you have obtained an API key from the Euskadi Open Data portal and replaced YOUR_API_KEY with your actual key.

import requests
import json

# Replace with your actual Euskalmet API Key
API_KEY = "YOUR_API_KEY"

# Example: Get current weather for Vitoria-Gasteiz (an arbitrary example location)
# You would typically find location IDs from Euskalmet's documentation or another endpoint.
# For demonstration, let's assume a simplified endpoint path for a specific municipality.
# The actual Euskalmet API structure involves specific endpoints for municipalities, zones, etc.
# Refer to the official Euskalmet API documentation for precise endpoint URLs and parameters:
# https://opendata.euskadi.eus/catalogo/-/euskalmet-api-de-prediccion-del-tiempo/

# This URL is illustrative. Please check the official Euskalmet API docs for correct endpoints.
# A common pattern might involve an endpoint like /weather/forecast/municipality/{municipalityId}/today
# For simplicity, we'll use a placeholder URL and structure that reflects typical API interaction.
# The Euskalmet API is structured around different 'resources' like 'forecast', 'observation', etc.
# and parameters for 'zones', 'municipalities', or 'days'.

# For a real integration, you would construct the URL based on Euskalmet's specific resource paths
# and parameters for fetching data for a particular municipality or zone.
# Example from docs could be: https://www.euskalmet.euskadi.eus/api/weather/forecast/municipality/20069/today/eu/web/euskalmet
# Note: The actual base URL and path segments must be confirmed from the Euskalmet API documentation.

# Let's use a hypothetical base URL and path for a general forecast for demonstration purposes.
# The Euskalmet API often requires a specific date format or resource identifier.
# For this example, we'll aim to get a general forecast, assuming an endpoint structure.

BASE_URL = "https://opendata.euskadi.eus/api/" # Placeholder, verify actual base URL
ENDPOINT_PATH = "weather/forecast/municipality/48020/today" # Example for Bilbao (48020)

headers = {
    "Accept": "application/json"
}

params = {
    "API-KEY": API_KEY, # Euskalmet often uses API-KEY in headers or as a query param
    "lang": "eu" # Basque language, or 'es' for Spanish
}

full_url = f"{BASE_URL}{ENDPOINT_PATH}"

try:
    response = requests.get(full_url, headers=headers, params=params)
    response.raise_for_status() # Raise an exception for HTTP errors (4xx or 5xx)

    data = response.json()
    print("Successfully fetched data:")
    print(json.dumps(data, indent=2, ensure_ascii=False))

    # Example of accessing data (structure depends on actual API response)
    if "forecast" in data and data["forecast"]:
        print("\nToday's forecast:")
        # Access specific elements based on the API response structure
        # For instance, if 'forecast' contains a list of daily forecasts
        # or detailed hourly predictions.
        # This part will need adjustment based on the actual JSON structure returned.
        # print(data["forecast"][0]["description"])

except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")
    if hasattr(e, 'response') and e.response is not None:
        print(f"Response status code: {e.response.status_code}")
        print(f"Response body: {e.response.text}")
except json.JSONDecodeError:
    print("Failed to decode JSON response.")
    print(f"Raw response: {response.text}")

Note: The exact endpoint path (ENDPOINT_PATH) and parameter names (e.g., API-KEY) should be verified against the official Euskalmet API documentation, as they are subject to change and specific to the data resource you wish to access (e.g., specific municipality, zone, or date). The example above uses a common pattern but might require adjustments for precise Euskalmet API endpoints.

Community libraries

Given Euskalmet's focus on providing a clear REST API and comprehensive documentation, community-contributed libraries often emerge to simplify access for specific programming languages or frameworks. These libraries are typically developed by individual developers or groups who find a need for a higher-level abstraction than direct HTTP calls.

Community libraries can offer:

  • Language-specific wrappers: Providing idiomatic interfaces for Python, JavaScript, PHP, etc.
  • Object-oriented models: Mapping API responses to native language objects, making data easier to manipulate.
  • Caching mechanisms: Implementing local caching to reduce redundant API calls and improve performance.
  • Framework integrations: Designed to work seamlessly within popular web frameworks (e.g., Django, Flask, React).

As of late 2024, specific widely adopted, officially endorsed community SDKs for Euskalmet are not prominently featured on the Euskadi Open Data portal. Developers looking for community libraries are encouraged to search public code repositories like GitHub or GitLab using terms such as "Euskalmet API Python" or "Euskalmet JavaScript client". When evaluating community libraries, consider:

  • Maintenance status: How recently was the library updated? Is it actively maintained?
  • Documentation: Is there clear documentation and examples?
  • Community support: Are there active issues or discussions?
  • License: Is the license compatible with your project?

For critical applications, it is often advisable to review the source code of community libraries to ensure they correctly implement the Euskalmet API specifications and handle errors robustly. If a suitable community library is not found, developing a custom client using standard HTTP libraries (as outlined in the official SDKs section) is a straightforward and reliable approach.

The Fetch API documentation provides a good general overview of how to interact with web APIs in modern JavaScript environments, which is applicable when no specific SDK is used.