Tutorial: Nominatim Geocoding

Geography

Data source: OpenStreetMap Nominatim

Overview

Nominatim Geocoding wraps OpenStreetMap Nominatim, handling authentication, pagination, and rate limits for you. This tutorial covers all 3 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-nominatim": {
      "url": "https://context.gnist.ai/mcp/nominatim/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (3)

`geocode_address`

Convert an address or place name to geographic coordinates. Forward geocoding: searches OpenStreetMap for matching places and returns coordinates, display name, and structured address components. Args: query: Address or place name (e.g. "Buckingham Palace", "Karl Johans gate 22, Oslo"). limit: Maximum results (1-20, default 5).

Parameter	Type	Required	Description
`query`	string	required
`limit`	integer	optional	(default: `5`)

curl -X POST "https://context.gnist.ai/mcp/nominatim/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "geocode_address", "arguments": {"query": "renewable energy"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/nominatim/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'renewable energy'},
            'name': 'geocode_address'}},
)
print(resp.json())

`reverse_geocode`

Convert geographic coordinates to a human-readable address. Reverse geocoding: looks up what's at the given latitude/longitude and returns the full address with structured components. Args: lat: Latitude (-90 to 90, e.g. 59.9139 for Oslo). lon: Longitude (-180 to 180, e.g. 10.7522 for Oslo).

Parameter	Type	Required	Description
`lat`	number	required
`lon`	number	required

curl -X POST "https://context.gnist.ai/mcp/nominatim/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "reverse_geocode", "arguments": {"lat": 59.91, "lon": 10.75}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/nominatim/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'lat': 59.91, 'lon': 10.75},
            'name': 'reverse_geocode'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/nominatim/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/nominatim/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does Nominatim Geocoding provide?

Forward and reverse geocoding — address to coordinates and coordinates to address. It exposes 3 tools: geocode_address, reverse_geocode, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the Nominatim Geocoding API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.