Nominatim Connector - Ismena website

info@ismena.com

Nominatim

Connector Details

Type

Virtual machines, Single VM , BYOL

Runs on

Google Compute Engine

Last Update

24 October, 2024

Category

Overview

The Nominatim Connector facilitates seamless integration with the Nominatim web service, providing access to geocoding, reverse geocoding, and other OpenStreetMap (OSM) data operations. This connector acts as a proxy to streamline data retrieval, supporting actions for searching OSM objects by name or type, reverse searching by location, looking up details by ID, querying server status, listing deletable objects, listing broken polygons, and retrieving internal object details for debugging.

Integration Overview

This document provides a detailed guide for each integration point, its purpose, configuration, and workflow support using the Nominatim Connector.

Supported Integration Action Points

search: Searches OSM objects by name or type.
reverse: Searches OSM objects by their location.
lookup: Looks up address details for OSM objects by their ID.
status: Queries the status of the server.
deletable: Lists objects that have been deleted in OSM but are held back in Nominatim in case the deletion was accidental.
polygons: Lists broken polygons detected by Nominatim.
details: Shows internal details for an object (for debugging only).

Detailed Integration Documentation

Search OSM Objects

Action	search
Purpose	Searches for OpenStreetMap objects based on a query string or specific types, with optional filters for location, language, and result format.
Parameters	Required: None (but typically requires q for effective searches). Optional: q: Free-form query string to search for (string, e.g., "London"). format: Output format (string, enum: ["xml", "json", "jsonv2", "geojson", "geocodejson"], default: "json"). limit: Maximum number of results to return (integer, minimum: 1, maximum: 50, default: 10). accept-language: Preferred language order for showing results, as a comma-separated list of language codes (string, e.g., "en,fr"). countrycodes: Limit search to a comma-separated list of country codes (string, e.g., "us,gb"). viewbox: Preferred area to find search results, in format '<x1>,<y1>,<x2>,<y2>' (string, e.g., "-0.5,51.3,0.5,51.7"). bounded: Restrict results to items within the viewbox (integer, enum: [0, 1], default: 0). addressdetails: Include a breakdown of the address into elements (integer, enum: [0, 1], default: 0). extratags: Include additional OSM tags in the result (integer, enum: [0, 1], default: 0). namedetails: Include a list of alternative names in the result (integer, enum: [0, 1], default: 0).
Configuration	Ensure the connector is configured with the appropriate environment variables, such as CONNECTOR_ENV_NOMINATIM_BASE_URL and CONNECTOR_ENV_PORT.
Output	Successful: Returns a JSON array of objects (or other specified format) with: place_id: Unique identifier (integer, e.g., 123456). licence: License information (string, e.g., "Data © OpenStreetMap contributors"). osm_type: OSM object type (string, e.g., "way"). osm_id: OSM object ID (integer, e.g., 789012). boundingbox: Array of bounding box coordinates (array of strings, e.g., ["51.5074", "51.5075", "-0.1278", "-0.1277"]). lat: Latitude (string, e.g., "51.5074"). lon: Longitude (string, e.g., "-0.1278"). display_name: Display name (string, e.g., "London, England, United Kingdom"). class: Object class (string, e.g., "place"). type: Object type (string, e.g., "city"). importance: Importance score (number, e.g., 0.9). address: Object with address breakdown (if addressdetails=1). extratags: Object with additional tags (if extratags=1). namedetails: Object with alternative names (if namedetails=1). Failure: Returns error details (e.g., status 400 for invalid parameters, 429 for too many requests).
Workflow Example	Execute the search action with q=London and format=json. Process the response to retrieve location details and coordinates. Use the data for mapping or address validation.

Reverse Geocoding

Action	reverse
Purpose	Performs reverse geocoding to find the nearest OSM object to a given latitude and longitude.
Parameters	Required: lat: Latitude of the point to reverse geocode (number, e.g., 51.5074). lon: Longitude of the point to reverse geocode (number, e.g., -0.1278). Optional: zoom: Level of detail required for the address (integer, minimum: 0, maximum: 18). format: Output format (string, enum: ["xml", "json", "jsonv2", "geojson", "geocodejson"], default: "json"). addressdetails: Include a breakdown of the address into elements (integer, enum: [0, 1], default: 0). extratags: Include additional OSM tags in the result (integer, enum: [0, 1], default: 0). namedetails: Include a list of alternative names in the result (integer, enum: [0, 1], default: 0).
Configuration	Ensure the connector is configured with the appropriate environment variables, such as CONNECTOR_ENV_NOMINATIM_BASE_URL and CONNECTOR_ENV_PORT.
Output	Successful: Returns a JSON object (or other specified format) with: place_id: Unique identifier (integer, e.g., 123456). licence: License information (string, e.g., "Data © OpenStreetMap contributors"). osm_type: OSM object type (string, e.g., "way"). osm_id: OSM object ID (integer, e.g., 789012). lat: Latitude (string, e.g., "51.5074"). lon: Longitude (string, e.g., "-0.1278"). display_name: Display name (string, e.g., "London, England, United Kingdom"). address: Object with address breakdown (if addressdetails=1). extratags: Object with additional tags (if extratags=1). namedetails: Object with alternative names (if namedetails=1). Failure: Returns error details (e.g., status 400 for invalid parameters, 429 for too many requests).
Workflow Example	Execute the reverse action with lat=51.5074, lon=-0.1278, and format=json. Process the response to obtain the address and details. Use the data for location-based services or mapping.

Lookup Address Details

Action	lookup
Purpose	Retrieves detailed address information for specified OSM object IDs.
Parameters	Required: osm_ids: Comma-separated list of OSM IDs in the format '[N\|W\|R]<id>' (string, e.g., "N123456,W789012"). Optional: format: Output format (string, enum: ["xml", "json", "jsonv2", "geojson", "geocodejson"], default: "json"). addressdetails: Include a breakdown of the address into elements (integer, enum: [0, 1], default: 0). extratags: Include additional OSM tags in the result (integer, enum: [0, 1], default: 0). namedetails: Include a list of alternative names in the result (integer, enum: [0, 1], default: 0).
Configuration	Ensure the connector is configured with the appropriate environment variables, such as CONNECTOR_ENV_NOMINATIM_BASE_URL and CONNECTOR_ENV_PORT.
Output	Successful: Returns a JSON array of objects (or other specified format) with: place_id: Unique identifier (integer, e.g., 123456). licence: License information (string, e.g., "Data © OpenStreetMap contributors"). osm_type: OSM object type (string, e.g., "node"). osm_id: OSM object ID (integer, e.g., 123456). lat: Latitude (string, e.g., "51.5074"). lon: Longitude (string, e.g., "-0.1278"). display_name: Display name (string, e.g., "London, England, United Kingdom"). address: Object with address breakdown (if addressdetails=1). extratags: Object with additional tags (if extratags=1). namedetails: Object with alternative names (if namedetails=1). Failure: Returns error details (e.g., status 400 for invalid parameters, 429 for too many requests).
Workflow Example	Execute the lookup action with osm_ids=N123456 and format=json. Process the response to retrieve detailed address information. Use the data for OSM object validation or enrichment.

Server Status Query

Action	status
Purpose	Returns the operational status of the Nominatim server.
Parameters	Required: None. Optional: format: Output format (string, enum: ["text", "json"], default: "text").
Configuration	Ensure the connector is configured with the appropriate environment variables, such as CONNECTOR_ENV_NOMINATIM_BASE_URL and CONNECTOR_ENV_PORT.
Output	Successful: Returns a JSON object (or text) with: status: Status code (integer, e.g., 0). message: Status message (string, e.g., "OK"). data_updated: Last data update timestamp (string, e.g., "2023-01-01T00:00:00Z"). Failure: Returns error details (e.g., status 429 for too many requests).
Workflow Example	Execute the status action with format=json. Check the response to verify server availability. Use the status for monitoring or before performing other operations.

List Deletable Objects

Action	deletable
Purpose	Lists OSM objects that have been deleted in OpenStreetMap but are retained in Nominatim in case the deletion was accidental.
Parameters	Required: None. Optional: format: Output format (string, enum: ["xml", "json"], default: "json").
Configuration	Ensure the connector is configured with the appropriate environment variables, such as CONNECTOR_ENV_NOMINATIM_BASE_URL and CONNECTOR_ENV_PORT.
Output	Successful: Returns a JSON array of objects (or XML) with: osm_type: OSM object type (string, e.g., "way"). osm_id: OSM object ID (integer, e.g., 789012). display_name: Display name (string, e.g., "Deleted Street"). Failure: Returns error details (e.g., status 429 for too many requests).
Workflow Example	Execute the deletable action with format=json. Review the list of retained deleted objects. Use the data for data integrity checks or recovery processes.

List Broken Polygons

Action	polygons
Purpose	Returns a list of broken polygons identified by Nominatim during processing.
Parameters	Required: None. Optional: format: Output format (string, enum: ["xml", "json"], default: "json").
Configuration	Ensure the connector is configured with the appropriate environment variables, such as CONNECTOR_ENV_NOMINATIM_BASE_URL and CONNECTOR_ENV_PORT.
Output	Successful: Returns a JSON array of objects (or XML) with: osm_type: OSM object type (string, e.g., "relation"). osm_id: OSM object ID (integer, e.g., 345678). display_name: Display name (string, e.g., "Broken Polygon Area"). Failure: Returns error details (e.g., status 429 for too many requests).
Workflow Example	Execute the polygons action with format=json. Identify broken polygons from the response. Use the data for debugging or OSM data maintenance.

Internal Object Details

Action	details
Purpose	Provides internal details for a specific OSM object, intended for debugging purposes.
Parameters	Required: osmtype: Type of OSM object (string, enum: ["N", "W", "R"], e.g., "N" for node). osmid: ID of the OSM object (integer, e.g., 123456). Optional: format: Output format (string, enum: ["json"], default: "json").
Configuration	Ensure the connector is configured with the appropriate environment variables, such as CONNECTOR_ENV_NOMINATIM_BASE_URL and CONNECTOR_ENV_PORT.
Output	Successful: Returns a JSON object with: place_id: Unique identifier (integer, e.g., 123456). osm_type: OSM object type (string, e.g., "node"). osm_id: OSM object ID (integer, e.g., 123456). category: Object category (string, e.g., "place"). type: Object type (string, e.g., "house"). admin_level: Administrative level (integer, e.g., 8). localname: Local name (string, e.g., "Example House"). names: Object with names (e.g., {"name": "Example House"}). address: Object with address details. extratags: Object with additional tags. geometry: Object with geometry information. Failure: Returns error details (e.g., status 400 for invalid parameters, 429 for too many requests).
Workflow Example	Execute the details action with osmtype=N and osmid=123456. Analyze the internal details for debugging. Use the data to troubleshoot OSM object issues.

Workflow Creation with the Connector

Example Workflow: Geocoding and Reverse Geocoding

Search for Location	Use the search action with q=London to find OSM objects matching the query. Retrieve coordinates and details for mapping.
Reverse Geocode Coordinates	Execute the reverse action with lat=51.5074 and lon=-0.1278 to get the address from coordinates. Process the address for validation or display.
Lookup OSM Details	Execute the lookup action with osm_ids=N123456 to fetch detailed information for a specific object. Enrich data with address breakdowns.
Check Server Status	Execute the status action to ensure the service is operational before further queries. Monitor for any issues like outdated data.

Pricing

bill-and-calculator-2023-11-27-05-25-06-utc 1

Request a Quote

Support

For Technical support please contact us on

custom-connectors-support@isolutions.sa

A tech solution company dedicated to providing innovation thus empowering businesses to thrive in the digital age.

Register to IBM x iSolution Event