French Address Search SDKs & Libraries: Integration Tools (2026)

SDKs overview

The French Address Search API, maintained by Etalab, provides access to the official French national address database, known as the Base Adresse Nationale (BAN) and Base Adresse Locale (BAL) data. While the API itself is a standard HTTP/REST interface, it does not officially provide dedicated Software Development Kits (SDKs) in the traditional sense, which often wrap API calls in language-specific objects and methods. Instead, it offers comprehensive documentation for direct API interaction primarily through cURL examples, enabling developers to integrate the service using any programming language capable of making HTTP requests. This approach aligns with the principles of RESTful API design, emphasizing statelessness and standard HTTP methods for resource manipulation, as described by the World Wide Web Consortium's architectural principles.

Despite the absence of official SDKs, the open nature of the API and its data has fostered a community of developers who have created various client libraries and wrappers in popular languages. These community-contributed tools simplify common tasks like address lookup, validation, and geocoding by abstracting the underlying HTTP requests and JSON parsing. Developers frequently utilize these libraries to accelerate integration, reduce boilerplate code, and handle API responses more idiomatically within their chosen programming environments.

The primary method for interacting with the French Address Search API remains direct HTTP requests, as detailed in the official API documentation. This direct approach offers maximum flexibility and control, allowing developers to tailor requests precisely to their application's needs without being constrained by an SDK's design choices. For many use cases, especially those requiring fine-grained control or minimal dependencies, direct HTTP client usage is often preferred.

Official SDKs by language

The French Address Search API does not feature official, language-specific SDKs. Instead, the API documentation emphasizes direct HTTP requests. Developers are provided with cURL examples to illustrate how to interact with the API endpoints for address search, geocoding, and reverse geocoding. This design choice means that integration typically involves using standard HTTP client libraries available in most programming languages.

The core interaction model relies on sending GET requests to specific endpoints and parsing the JSON responses. For instance, a search query for an address would involve a GET request to /search/ with parameters like q (query string) and limit. The API's responses adhere to a consistent JSON structure, facilitating parsing across different programming environments.

The table below summarizes the official support:

Installation

Since there are no official SDKs, installation for integrating with French Address Search primarily involves setting up an HTTP client library in your chosen programming language. These libraries are widely available and typically installed via standard package managers.

Python

For Python, the requests library is a common choice for making HTTP requests due to its user-friendly API. To install:

pip install requests

JavaScript (Node.js)

In Node.js environments, axios is a popular promise-based HTTP client. Alternatively, the native fetch API is available in modern Node.js versions and browsers. To install axios:

npm install axios

Java

For Java, OkHttp is a widely used and efficient HTTP client. If using Maven, add the following to your pom.xml:

<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>4.12.0</version>
</dependency>

For Gradle, add to your build.gradle:

implementation 'com.squareup.okhttp3:okhttp:4.12.0'

The OkHttp documentation provides further installation and usage details.

PHP

For PHP projects, GuzzleHttp is a robust HTTP client. Install it via Composer:

composer require guzzlehttp/guzzle

Quickstart example

This example demonstrates how to perform a basic address search using the French Address Search API with Python's requests library. The goal is to find addresses matching a query string.

Python Quickstart

First, ensure you have the requests library installed (pip install requests).

import requests
import json

# Base URL for the French Address Search API
API_BASE_URL = "https://api-adresse.data.gouv.fr"

def search_address(query):
    """
    Performs an address search using the French Address Search API.
    :param query: The address string to search for (e.g., "8 bd du port").
    :return: A dictionary containing the API response, or None on error.
    """
    endpoint = f"{API_BASE_URL}/search/"
    params = {
        "q": query,
        "limit": 5  # Limit results to 5
    }

    try:
        response = requests.get(endpoint, params=params)
        response.raise_for_status()  # Raise an HTTPError for bad responses (4xx or 5xx)
        return response.json()
    except requests.exceptions.HTTPError as http_err:
        print(f"HTTP error occurred: {http_err}")
    except requests.exceptions.ConnectionError as conn_err:
        print(f"Connection error occurred: {conn_err}")
    except requests.exceptions.Timeout as timeout_err:
        print(f"Timeout error occurred: {timeout_err}")
    except requests.exceptions.RequestException as req_err:
        print(f"An unexpected error occurred: {req_err}")
    return None

if __name__ == "__main__":
    search_query = "8 boulevard du port marseille"
    results = search_address(search_query)

    if results:
        print(f"Search results for '{search_query}':")
        if results.get("features"):
            for feature in results["features"]:
                properties = feature["properties"]
                geometry = feature["geometry"]
                print(f"  Address: {properties.get('label')}")
                print(f"  Score: {properties.get('score')}")
                print(f"  City: {properties.get('city')}")
                print(f"  Postcode: {properties.get('postcode')}")
                print(f"  Coordinates: {geometry.get('coordinates')}")
                print("---------------------")
        else:
            print("  No addresses found.")
    else:
        print("Failed to retrieve search results.")

This Python script defines a function search_address that takes a query string, constructs the API request with appropriate parameters, and handles potential network or HTTP errors. It then parses the JSON response and prints key details for each found address, such as the label, score, city, postcode, and coordinates. This demonstrates a fundamental interaction pattern for integrating the French Address Search API into applications.

Community libraries

Given the absence of official SDKs, the developer community has created several libraries to facilitate interaction with the French Address Search API. These libraries often wrap the API's RESTful endpoints in more idiomatic language constructs, simplifying common tasks and handling JSON parsing.

Python

• ban-api-python: A Python client for the Base Adresse Nationale API. This library aims to provide a convenient interface for searching and validating French addresses within Python applications. It abstracts the HTTP requests and provides Pythonic objects for API responses. Developers can typically install it via pip.
• py-adresse-data-gouv-fr: Another community-driven Python wrapper that offers functions for geocoding, reverse geocoding, and address search. It focuses on ease of use and integrates well with typical Python data processing workflows.

JavaScript / Node.js

• node-adresse-data-gouv-fr: A Node.js client library that simplifies interaction with the French Address Search API. It provides methods for address search, reverse geocoding, and other API functionalities, typically returning promises for asynchronous operations. This library is installable via npm.
• Various frontend wrappers: Many developers integrate the API directly into browser-based applications using the native fetch API or libraries like axios, often building custom utility functions to manage requests and responses specific to their application's needs.

PHP

• adresse-data-gouv-fr-php: A PHP client library that provides a wrapper for the API, allowing PHP developers to easily perform address lookups and validation. It typically uses GuzzleHttp internally for making HTTP requests.

These community-maintained libraries often provide benefits such as:

• Simplified API calls: Abstracting the need to manually construct URLs and handle HTTP headers.
• Object-oriented responses: Converting raw JSON responses into language-specific objects, making data access more intuitive.
• Error handling: Providing more structured error reporting than raw HTTP status codes.
• Community support: Leveraging shared knowledge and contributions from other developers.

When choosing a community library, developers should evaluate its active maintenance, documentation quality, and alignment with their project's specific requirements. The Mozilla Developer Network's guide on the Fetch API provides a good starting point for direct browser-based integrations.