Nominatim OSM API Module (Legacy)

Common errors

• ImportError: No module named nominatim

  cause Attempting to install or import 'nominatim' on a system where pip is linked to Python 3, or the package cannot be found due to being very old/unmaintained.
  fix Ensure you are using a Python 2.7 environment for installation and execution. For modern Python, consider `pip install geopy` and use its Nominatim geocoder instead.

• TypeError: 'str' object is not callable (related to print statement)

  cause Running Python 2.7 code (e.g., `print response`) in a Python 3 environment. The legacy `nominatim` library uses Python 2.7 syntax.
  fix Execute the code in a Python 2.7 interpreter. Alternatively, rewrite the code to conform to Python 3 syntax (`print(response)`), though other incompatibilities may still arise.

• HTTPSConnectionPool(host='your_nominatim_host', port=443): Max retries exceeded with url: ... (Caused by ReadTimeoutError("..."))

  cause The legacy library might have issues with modern SSL certificates, network configurations, or the target Nominatim server (if self-hosted) is not responding or configured correctly.
  fix Verify the reachability and configuration of your self-hosted Nominatim server. For public Nominatim services, switch to a modern library like `geopy` which handles network requests and SSL more robustly. Ensure your `user_agent` is set correctly and observe usage policies if using public APIs.

Warnings

• breaking This library is designed for Python 2.7. Using it with Python 3 will result in `ImportError` or `SyntaxError` due to incompatible language features (e.g., `print` statement vs. function, module structure).
  Fix: Use a Python 2.7 environment or migrate to modern alternatives like `geopy` (for public Nominatim API) or `nominatim-api` (for local Nominatim database access).
• deprecated The `nominatim` package (v0.1) has not been updated since 2014 and is considered abandoned. It targets a potentially outdated Nominatim API endpoint (PHP frontend) and is not compatible with current Nominatim server versions without significant modification.
  Fix: Avoid using this library for new projects. For web service interaction, use `geopy`. For local Nominatim database interaction, use `nominatim-api` and `nominatim-db`.
• gotcha This library is distinct from the current official Nominatim Python frontend packages (`nominatim-api`, `nominatim-db`) and `geopy`. It is *not* for querying `nominatim.openstreetmap.org` directly, but rather for a self-hosted instance.
  Fix: Carefully review your project requirements. If you need to query the public Nominatim service, use `geopy`. If you need to build and query a local Nominatim database, refer to `nominatim-api` and `nominatim-db` documentation.

Install

• pip install nominatim Install (Python 2.7 only)

Imports

• ReverseGeocoder
  wrong:

  from geopy.geocoders import Nominatim

  correct:

  from nominatim import ReverseGeocoder

  The 'nominatim' package is distinct from 'geopy' which is a modern geocoding library including Nominatim support. The legacy 'nominatim' package is for a self-hosted or local Nominatim instance, not the official public API via geopy.

Quickstart

This quickstart demonstrates how to use the legacy `nominatim` library to perform reverse geocoding against a *local or self-hosted* Nominatim instance. It highlights the `ReverseGeocoder` class and its `geocode` method. Due to the library's age, the example uses Python 2.7 print syntax and explicitly warns that for modern applications, especially those using the public Nominatim API, `geopy` is the recommended alternative.

import os
from nominatim import ReverseGeocoder

# This legacy library is designed to connect to a self-hosted Nominatim instance.
# The URL would point to your local Nominatim reverse.php endpoint.
# For public Nominatim API, use the 'geopy' library instead.

# Example for a local/self-hosted Nominatim (requires a running Nominatim PHP frontend)
# Note: This code uses Python 2.7 print syntax and assumes a local Nominatim setup.
# To run on modern Python, this example would need significant modification.

try:
    # Assuming a local Nominatim installation available at this URL
    # The actual URL might vary based on your Nominatim server setup.
    # This is illustrative for the *original* library's intended use.
    nominatim_url = os.environ.get('NOMINATIM_LOCAL_URL', 'http://127.0.0.1/nominatim/reverse.php?format=json')
    client = ReverseGeocoder(nominatim_url)
    
    # Example coordinates (Melbourne, Australia)
    latitude = -37.856206
    longitude = 145.233980
    
    print(f"Attempting to reverse geocode {latitude}, {longitude} using legacy nominatim library...")
    response = client.geocode(latitude, longitude)

    if response and 'full_address' in response:
        print(f"Full Address: {response['full_address']}")
    elif response:
        print(f"Raw response (no 'full_address'): {response}")
    else:
        print("No response or error from Nominatim.")

except ImportError:
    print("Error: The 'nominatim' library is not installed or requires Python 2.7.")
except Exception as e:
    print(f"An error occurred: {e}")

# For modern Python and public Nominatim API, consider geopy:
# from geopy.geocoders import Nominatim
# geolocator = Nominatim(user_agent="my-app-name")
# location = geolocator.reverse("52.509669, 13.376294")
# print(location.address)