Nominatim SDKs & Libraries: Official & Community Integrations (2026)

SDKs overview

Nominatim, an open-source geocoding engine built on OpenStreetMap data, offers various Software Development Kits (SDKs) and libraries to facilitate its integration into diverse applications. These tools abstract the underlying HTTP API, simplifying tasks such as constructing query URLs, handling API keys (if applicable for public instances), and parsing JSON responses. While Nominatim itself is a server-side application that developers typically self-host or utilize through public instances, the SDKs and libraries are client-side components designed to interact with a running Nominatim instance.

The availability of both officially recognized and community-contributed libraries reflects Nominatim's open-source nature. Official libraries often provide direct support for core functionalities and are maintained by contributors closely associated with the Nominatim project. Community libraries extend this ecosystem, offering specialized features, support for less common programming languages, or alternative approaches to interaction. Developers selecting an SDK should consider factors such as language compatibility, active maintenance, feature set, and the specific licensing terms of the library.

For detailed information on the Nominatim API endpoints and request/response formats, refer to the Nominatim API reference documentation. Understanding the API directly can be beneficial when using libraries, especially for debugging or implementing advanced query parameters not fully exposed by a particular SDK.

Official SDKs by language

While Nominatim's core project primarily focuses on the server-side geocoding engine, several client-side libraries are widely recognized within the community as de facto or officially supported integration tools due to their prevalence and active maintenance. These libraries aim to streamline common tasks, such as searching for addresses, reverse geocoding coordinates, and handling search parameters.

The following table lists prominent libraries often used for interacting with Nominatim instances, detailing their language, package name, typical installation command, and general maturity level. It's important to note that "official" in this context often refers to libraries that are well-established and recommended by the broader Nominatim and OpenStreetMap communities, rather than being developed and maintained by a central Nominatim development team.

These libraries typically handle URL encoding, HTTP requests, and basic JSON parsing, allowing developers to focus on integrating geocoding results into their application logic. For instance, the geopy library for Python supports various geocoding services, including Nominatim, by providing a unified interface for location lookup geopy documentation.

Installation

Installation procedures for Nominatim client libraries typically follow standard practices for their respective programming language ecosystems. Developers usually use package managers to add these libraries to their projects. Below are examples for installing some of the commonly used libraries:

Python (using geopy)

The geopy library is a popular choice for Python developers due to its support for multiple geocoding services, including Nominatim. To install geopy:

pip install geopy

This command downloads and installs the geopy package and its dependencies from the Python Package Index (PyPI).

JavaScript (using node-nominatim)

For Node.js environments, node-nominatim provides a straightforward way to interact with Nominatim. Install it via npm:

npm install node-nominatim

This adds the package to your project's node_modules directory and updates your package.json file.

PHP (using geocoder-php/nominatim-provider)

PHP projects often use the Geocoder-PHP library, which offers a Nominatim provider. Installation is typically managed with Composer:

composer require geocoder-php/nominatim-provider

Composer will resolve dependencies and install the necessary files into your project's vendor/ directory. More information on installing PHP packages with Composer is available in the Composer installation guide.

Java (using nominatim-java)

For Java applications, libraries like nominatim-java can be integrated using build tools such as Maven or Gradle. For Maven, add the following dependency to your pom.xml:

<dependency>
    <groupId>com.github.jd-alexander</groupId>
    <artifactId>nominatim-java</artifactId>
    <version>2.0.0</version> <!-- Check for the latest version -->
</dependency>

For Gradle, add it to your build.gradle file:

implementation 'com.github.jd-alexander:nominatim-java:2.0.0' // Check for the latest version

Always consult the specific library's documentation for the most current installation instructions and version compatibility.

Quickstart example

This quickstart example demonstrates how to perform a simple geocoding query using the geopy library in Python to interact with a Nominatim instance. This example assumes you have Python and geopy installed.

First, ensure you have geopy installed:

pip install geopy

Next, use the following Python code to geocode an address:

from geopy.geocoders import Nominatim
from geopy.exc import GeocoderTimedOut, GeocoderServiceError

# Initialize the Nominatim geocoder
# It's good practice to provide a unique user_agent for your application
geolocator = Nominatim(user_agent="my-nominatim-app-name")

address = "1600 Amphitheatre Parkway, Mountain View, CA"

try:
    # Perform the geocoding query
    location = geolocator.geocode(address, timeout=10)

    if location:
        print(f"Address: {location.address}")
        print(f"Latitude: {location.latitude}")
        print(f"Longitude: {location.longitude}")
        print(f"Raw data: {location.raw}")
    else:
        print(f"Could not find coordinates for: {address}")

except GeocoderTimedOut:
    print("Geocoding service timed out. Please try again later.")
except GeocoderServiceError as e:
    print(f"Geocoding service error: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

This script initializes the Nominatim geocoder, specifies a user agent (which is crucial for public Nominatim instances to identify your application and adhere to usage policies), and then attempts to geocode a given address. It includes basic error handling for common issues like timeouts or service errors. The location object returned by geocode() contains attributes like address, latitude, and longitude, as well as raw data for full API response details.

For reverse geocoding (finding an address from coordinates), the process is similar:

from geopy.geocoders import Nominatim

geolocator = Nominatim(user_agent="my-nominatim-app-name")

latitude = 37.4220656
longitude = -122.0840897

try:
    location = geolocator.reverse(f"{latitude}, {longitude}", timeout=10)

    if location:
        print(f"Coordinates: ({latitude}, {longitude})")
        print(f"Address: {location.address}")
    else:
        print(f"Could not find address for coordinates: ({latitude}, {longitude})")

except Exception as e:
    print(f"An error occurred during reverse geocoding: {e}")

These examples connect to the default Nominatim public server (https://nominatim.openstreetmap.org/). If you are running a self-hosted Nominatim instance, you would configure the Nominatim object with the base_url parameter pointing to your instance's endpoint.

Community libraries

Beyond the widely adopted libraries, the Nominatim ecosystem benefits from various community-contributed tools that cater to specific needs or languages. These libraries are typically found on platforms like GitHub and can range from experimental projects to well-maintained alternatives.

• Go: Several Go packages exist for interacting with Nominatim, often found by searching for "nominatim go" on GitHub. These typically provide structs for request/response bodies and client methods for making API calls.
• Rust: Similar to Go, Rust developers can find community-driven crates that offer wrappers for Nominatim's API. These often leverage Rust's strong type system for robust API interactions.
• Front-end JavaScript frameworks: While node-nominatim is suitable for server-side JavaScript, front-end developers often directly use fetch or XMLHttpRequest to interact with Nominatim, sometimes wrapped in custom utility functions or small libraries within their specific framework (e.g., React, Vue, Angular) to manage state and display results. These are not typically standalone packages but rather patterns of usage.
• Shell scripting: For simple, one-off queries or automation, curl or wget can be used directly to interact with the Nominatim API, parsing the JSON output with tools like jq. This approach is common for quick tests or command-line utilities. For instance, a basic geocode query can be done with curl "https://nominatim.openstreetmap.org/search?q=berlin&format=json".

When considering a community library, it is advisable to check its GitHub repository for:

• Last commit date: Indicates active maintenance.
• Number of stars/forks: Suggests community adoption and interest.
• Open issues/pull requests: Provides insight into responsiveness to bugs and feature requests.
• Documentation: Clear and comprehensive documentation is a strong indicator of a well-supported library.
• License: Ensure the license is compatible with your project's requirements.

The OpenStreetMap wiki and forums are excellent resources for discovering and discussing community-led projects related to Nominatim, offering insights into their use cases and reliability. Developers can also find examples and discussions on general geocoding practices and library recommendations on developer community sites like Mozilla Developer Network's Geolocation API guide, which, while not specific to Nominatim, covers foundational concepts relevant to location services.