Open Government, Finland: Getting Started with Avoindata.fi APIs (2026)

Getting started overview

Open Government, Finland, through its Avoindata.fi portal, provides public sector open data using the CKAN platform. Accessing this data programmatically requires understanding the CKAN API, which facilitates interaction with datasets, resources, and metadata. The portal's entire data catalog is available without charge, making it accessible for developers, researchers, and citizens.

The process of getting started involves three primary steps:

1. Account Creation: Registering on the Avoindata.fi portal to gain access to personalized features, including API key generation.
2. API Key Retrieval: Generating and securing an API key, which authenticates requests to the CKAN API.
3. First Request: Constructing and executing a basic API call to retrieve data or metadata, confirming successful integration.

This guide focuses on these foundational steps, providing a pathway to initial data retrieval. For detailed information on specific API endpoints and advanced functionalities, refer to the Avoindata.fi API documentation.

Quick Reference Steps

Create an account and get keys

Access to the Avoindata.fi CKAN API primarily uses API keys for authentication, although many public data endpoints do not strictly require them for read operations. An API key becomes necessary when performing actions that require user context, such as modifying datasets (if permissions allow) or accessing certain user-specific metadata. Regardless, obtaining an API key is a recommended practice for consistency and future-proofing your integration, as it identifies your application to the platform and can provide higher rate limits or access to specific datasets if granted.

Account Registration

1. Navigate to the registration page: Open your web browser and go to the official Avoindata.fi registration portal.
2. Provide required details: Fill in the registration form with your desired username, a valid email address, and a secure password. Ensure the email address is accessible as it will be used for verification.
3. Complete verification: After submitting the form, follow the instructions in the verification email sent to your registered address to activate your account. This step confirms ownership of the email and finalizes the account creation.
4. Login to your account: Once verified, log in to your newly created account on Avoindata.fi.

Generating an API Key

After successfully logging into your Avoindata.fi account, you can generate your API key.

1. Access your user profile: Click on your username in the top right corner of the Avoindata.fi portal and select 'My Profile' or 'Account Settings'.
2. Locate API Key section: Within your profile settings, look for a section labeled 'API Key' or 'Developer Settings'. The precise location may vary slightly based on updates to the portal's user interface.
3. Generate or view key: If an API key is not displayed, there will typically be an option to 'Generate API Key' or 'Show API Key'. Click this button to reveal your unique alphanumeric key.
4. Securely store your key: Copy the generated API key immediately and store it in a secure location. Treat your API key like a password; do not hardcode it directly into client-side code, commit it to version control, or share it publicly. For server-side applications, consider using environment variables or a secrets management service to protect the API key.

The CKAN API often uses the Authorization header with the API key for authenticated requests, following a pattern similar to Authorization: YOUR_API_KEY. This is a common practice for RESTful APIs to ensure that requests originate from legitimate users or applications, as detailed in general HTTP Authorization header specifications.

Your first request

With an account created and an API key secured, you are ready to make your first request to the Avoindata.fi CKAN API. This initial call will typically be a read operation to retrieve a list of available datasets, confirming your setup is correct.

Understanding the CKAN API Endpoint

The CKAN API follows a standardized structure. The base URL for the Avoindata.fi API is https://www.avoindata.fi/api/3/action/. All API actions (e.g., listing packages, showing a specific package) are appended to this base URL.

A common starting point is the package_list action, which returns a list of all dataset identifiers (package names) on the portal. This action does not typically require an API key for read access.

Example Request (Python)

This example uses Python with the requests library, a common choice for making HTTP requests:

import requests
import json

# Replace with your actual Avoindata.fi API key if needed for other actions
# For package_list, it's often not strictly required, but good practice to include if available
api_key = "YOUR_API_KEY" # Leave empty string if not using auth for this call

base_url = "https://www.avoindata.fi/api/3/action/"
endpoint = "package_list"

headers = {
    "Content-Type": "application/json",
    # "Authorization": api_key # Uncomment if your API key is required
}

try:
    response = requests.get(f"{base_url}{endpoint}", headers=headers)
    response.raise_for_status() # Raise an exception for HTTP errors (4xx or 5xx)

    data = response.json()

    if data["success"]:
        print("Successfully retrieved package list:")
        # Print the first 5 package names for brevity
        for i, package_name in enumerate(data["result"][:5]):
            print(f"  - {package_name}")
        print(f"Total packages: {len(data['result'])}")
    else:
        print(f"API request failed: {data.get('error', 'Unknown error')}")

except requests.exceptions.RequestException as e:
    print(f"An error occurred during the request: {e}")
except json.JSONDecodeError:
    print("Failed to decode JSON response.")
except KeyError:
    print("Unexpected JSON structure or missing 'success' key.")

Running the Python Example:

1. Install requests: If you don't have it, install the requests library: pip install requests.
2. Save the code: Save the code above as a .py file (e.g., avoindata_test.py).
3. Execute: Run it from your terminal: python avoindata_test.py.

A successful response will print a list of dataset identifiers, indicating that your environment is configured correctly and you can communicate with the Avoindata.fi API.

Example Request (JavaScript using Fetch API)

For client-side applications or Node.js environments, the Fetch API provides a promise-based interface for making web requests:

const API_KEY = "YOUR_API_KEY"; // Replace with your actual API key, if needed
const BASE_URL = "https://www.avoindata.fi/api/3/action/";
const ENDPOINT = "package_list";

async function getPackageList() {
    try {
        const response = await fetch(`${BASE_URL}${ENDPOINT}`, {
            method: 'GET',
            headers: {
                'Content-Type': 'application/json',
                // 'Authorization': API_KEY // Uncomment if your API key is required
            }
        });

        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }

        const data = await response.json();

        if (data.success) {
            console.log("Successfully retrieved package list:");
            data.result.slice(0, 5).forEach(packageName => {
                console.log(`  - ${packageName}`);
            });
            console.log(`Total packages: ${data.result.length}`);
        } else {
            console.error("API request failed:", data.error || 'Unknown error');
        }
    } catch (error) {
        console.error("An error occurred during the request:", error);
    }
}

getPackageList();

This JavaScript example can be run in a browser's developer console or within a Node.js environment (after ensuring fetch is available, e.g., using node-fetch for older Node versions). It demonstrates how to retrieve a list of packages and handle potential errors.

Common next steps

After successfully making your first request, several common next steps can deepen your interaction with the Avoindata.fi platform:

1. Explore other API actions: The CKAN API offers numerous actions beyond package_list. Investigate package_show to retrieve detailed metadata for a specific dataset, resource_show to get details about a file within a dataset, and datastore_search for querying tabular data directly. Refer to the official Avoindata.fi API documentation for a full list of available actions and their parameters.
2. Filter and search data: Learn how to use query parameters to filter dataset lists or search within specific datasets. The CKAN API supports various search functionalities that can help you pinpoint relevant information more efficiently.
3. Work with specific data formats: Avoindata.fi hosts data in various formats, including CSV, JSON, XML, and geospatial formats. Understand how to parse and utilize data from these different formats once retrieved through the API. The W3C's Data on the Web Best Practices provides foundational guidance on handling diverse web data formats.
4. Implement error handling: Build robust error handling into your applications to gracefully manage API rate limits, network issues, or malformed requests. The CKAN API returns specific error codes and messages that can be used for debugging.
5. Contribute data (if applicable): If you are a public sector entity or authorized user, explore the process of publishing data to the Avoindata.fi portal using the API. This typically involves using authenticated POST requests.
6. Monitor API usage: While Avoindata.fi does not typically charge for data access, monitoring your API usage can help you understand your application's behavior and avoid unexpected rate limiting or performance issues.

Troubleshooting the first call

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

• Check API Key: Ensure your API key (if used) is correctly placed in the Authorization header. Double-check for typos or leading/trailing spaces. Remember that many read-only CKAN endpoints, like package_list, do not require an API key at all.
• Verify Endpoint URL: Confirm that the base URL (https://www.avoindata.fi/api/3/action/) and the specific action (e.g., package_list) are precisely correct. Incorrect URLs are a frequent source of 404 Not Found errors.
• HTTP Status Codes: Pay attention to the HTTP status code returned in the response. Common codes include:
  • 200 OK: Success. The request was processed as expected.
  • 400 Bad Request: The request was malformed, or required parameters were missing. Check your request body and parameters.
  • 403 Forbidden: Authentication failed (e.g., invalid API key) or you lack permissions for the requested action.
  • 404 Not Found: The requested resource or endpoint does not exist. Verify the URL.
  • 5xx Server Error: An issue on the Avoindata.fi server. These are generally outside your control; try again later.
• JSON Parsing Errors: If you receive an error stating that the JSON response cannot be parsed, inspect the raw response body. It might contain an HTML error page, plain text, or malformed JSON. This often indicates a non-200 HTTP status code that was not handled.
• Network Connectivity: Ensure your development environment has an active internet connection and no firewall rules are blocking outgoing HTTP requests to avoindata.fi.
• Rate Limiting: While less common for simple read operations on open data portals, intensive usage might trigger rate limits. If you receive a 429 Too Many Requests status, introduce delays between your calls or reduce the frequency of your requests.
• Consult API Documentation: The Avoindata.fi API documentation is the authoritative source for troubleshooting specific endpoints and understanding expected request/response formats.