Getting started overview

Integrating with the adresse.data.gouv.fr API involves direct HTTP requests to its RESTful endpoints. The service is designed for applications requiring geocoding, reverse geocoding, or address search functionalities specifically for French addresses. Unlike many commercial APIs, adresse.data.gouv.fr does not require an API key or account creation for basic usage, streamlining the initial setup process. This guide provides the steps to make your first successful API call.

The API adheres to standard REST principles, allowing interaction via HTTP GET requests. Responses are provided in JSON format, which is a common data interchange format for web APIs, as described by the JSON:API specification. Understanding basic HTTP request structures and JSON parsing is beneficial for integration.

Key features for getting started

  • No API Key: Direct access without credential management.
  • RESTful Endpoints: Standard HTTP GET requests for all operations.
  • JSON Responses: Consistent data format for parsing.
  • Geocoding: Convert an address string to geographic coordinates.
  • Reverse Geocoding: Convert geographic coordinates to the nearest address.
  • Address Search: Autocomplete and search for addresses based on partial input.

Quick Start Reference

Step What to do Where to find information
1. Understand API Access Confirm no API key is needed. adresse.data.gouv.fr API Documentation
2. Choose Endpoint Select geocoding, reverse geocoding, or search endpoint. adresse.data.gouv.fr API Endpoints
3. Construct Request Build your HTTP GET request URL with parameters. Request examples in documentation
4. Execute Request Use curl or an HTTP client in your preferred language. Example curl commands
5. Parse Response Process the JSON output to extract address data. JSON response structure

Create an account and get keys

For the primary API services offered by adresse.data.gouv.fr, including geocoding, reverse geocoding, and address search, no account creation or API key is required. The service is openly accessible to facilitate public sector initiatives and general use cases within France. This simplifies the onboarding process significantly as developers can immediately begin making requests without administrative overhead.

This approach contrasts with many commercial geospatial APIs, such as the Google Geocoding API or Stripe's API authentication, which typically mandate API keys for rate limiting, billing, and security purposes. The absence of an API key for adresse.data.gouv.fr means that you can proceed directly to constructing and executing your first API request.

While the main API does not require keys, certain advanced or administrative functionalities not covered in this Getting Started guide might have different access requirements. Always refer to the official adresse.data.gouv.fr API documentation for the most current and comprehensive access policies.

Your first request

This section outlines how to make a basic geocoding request to the adresse.data.gouv.fr API using curl, a common command-line tool for making HTTP requests. This will convert a human-readable address into geographical coordinates (latitude and longitude).

Geocoding an address

The primary geocoding endpoint is /search/. You pass the address query as a parameter.

Request structure

The base URL for the API is https://api-adresse.data.gouv.fr. To search for an address, you append /search/ followed by query parameters. The most essential parameter is q, which holds the address string you want to geocode.

For example, to geocode the address "8 rue du Printemps, Paris", the URL would be:

GET https://api-adresse.data.gouv.fr/search/?q=8+rue+du+Printemps%2C+Paris HTTP/1.1
Host: api-adresse.data.gouv.fr

Using curl

Open your terminal or command prompt and execute the following curl command:

curl "https://api-adresse.data.gouv.fr/search/?q=8+rue+du+Printemps%2C+Paris"

This command sends an HTTP GET request to the geocoding endpoint with the specified address query. The + sign or %20 URL-encodes spaces in the query string, which is a standard practice for URL parameters.

Expected response

A successful request will return a JSON object containing a features array. Each feature represents a geocoded result, with detailed address information and geographical coordinates. The first feature in the array is typically the most relevant result.

{
  "type": "FeatureCollection",
  "version": "0.8",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [2.301538, 48.878771]
      },
      "properties": {
        "label": "8 Rue du Printemps 75017 Paris",
        "score": 0.9,
        "id": "75117_7621",
        "name": "8 Rue du Printemps",
        "postcode": "75017",
        "citycode": "75117",
        "city": "Paris",
        "context": "75, Paris, Île-de-France",
        "housenumber": "8",
        "street": "Rue du Printemps",
        "importance": 0.6,
        "distance": 0
      }
    }
  ],
  "attribution": "BAN",
  "licence": "ETALAB-2.0",
  "query": "8 rue du Printemps, Paris",
  "limit": 5
}

In this response, the coordinates array within geometry provides the longitude (2.301538) and latitude (48.878771) for the geocoded address. The properties object includes additional structured address components.

Reverse geocoding coordinates

To convert coordinates back to an address, use the /reverse/ endpoint with lon (longitude) and lat (latitude) parameters.

curl "https://api-adresse.data.gouv.fr/reverse/?lon=2.301538&lat=48.878771"

This request should return a similar JSON structure, with the features array containing details of the address closest to the provided coordinates.

Common next steps

After successfully making your first requests to adresse.data.gouv.fr, consider these common next steps for further integration and development:

  1. Explore additional API features: The API offers more advanced search parameters, such as filtering by postcode or city, and precision settings. Consult the adresse.data.gouv.fr API documentation for a full list of available parameters and endpoints, including batch geocoding.

  2. Integrate into your application: Move beyond curl and integrate the API calls into your chosen programming language (e.g., Python, JavaScript, Node.js). Use an HTTP client library appropriate for your language (e.g., requests in Python, fetch or axios in JavaScript) to manage requests and parse JSON responses. Many frameworks and libraries provide abstractions for JSON-LD data structures, often used in geospatial contexts.

  3. Handle rate limits and errors: While adresse.data.gouv.fr is free and openly accessible, all public APIs have usage policies and potential rate limits to ensure fair use. Although no specific rate limit is prominently documented for the primary API, it is good practice to implement retry logic and handle HTTP status codes (e.g., 429 Too Many Requests, 500 Internal Server Error) gracefully in your application. The API documentation often provides guidance on error responses.

  4. Implement client-side geocoding: For interactive maps or address input fields, consider using client-side JavaScript libraries that can interact with the API, providing autocomplete suggestions as users type. This enhances user experience by reducing input errors and speeding up address entry.

  5. Data validation and caching: Implement validation on user inputs before sending them to the API to reduce unnecessary requests and improve data quality. For frequently requested addresses, consider caching results to reduce API calls and improve application performance.

Troubleshooting the first call

When making your first API call, you might encounter issues. Here are common problems and their solutions:

HTTP Status Codes

  • 400 Bad Request: This usually means your request URL is malformed or missing required parameters. Double-check your URL encoding (e.g., spaces converted to %20 or +) and ensure all necessary parameters (like q for search or lat/lon for reverse geocoding) are present. Review the API documentation's parameter section carefully.

  • 404 Not Found: This indicates that the endpoint you are trying to reach does not exist. Verify the base URL (https://api-adresse.data.gouv.fr) and the specific endpoint path (e.g., /search/, /reverse/). Typographical errors are common culprits here.

  • 500 Internal Server Error: This is a server-side error, meaning something went wrong on adresse.data.gouv.fr's end. This is less common for simple requests, but if it occurs, wait a moment and retry your request. If the issue persists, check the official service status pages if available, or consider contacting adresse.data.gouv.fr support.

Response Issues

  • Empty features array: If the features array in the JSON response is empty, it means the API could not find a match for your query. This can happen for several reasons:

    • Incorrect address details: The address might be misspelled, incomplete, or simply not recognized by the database. Try simplifying the query (e.g., just street and city) or using a known valid French address for testing.
    • Scope limitations: The API is optimized for French addresses. Queries for addresses outside of France are unlikely to yield results.

  • Unexpected JSON structure: Ensure your JSON parser is robust and accounts for potential variations in the response, although the API aims for consistency. Always refer to the API documentation for the expected JSON schema.

Network Connectivity

  • curl: (6) Could not resolve host: Your machine cannot resolve the domain name api-adresse.data.gouv.fr. Check your internet connection, DNS settings, or any local firewall rules that might be blocking outbound HTTP requests.

  • Timeout errors: If the request takes too long and times out, it could be due to network latency, a temporary server issue, or an overly complex query. Implement appropriate timeouts in your client and consider retrying with exponential backoff.