Tutorial: OpenStreetMap POI

Geography

Data source: OpenStreetMap / Overpass

Overview

OpenStreetMap POI wraps OpenStreetMap / Overpass, handling authentication, pagination, and rate limits for you. This tutorial covers all 5 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-osm-poi": {
      "url": "https://context.gnist.ai/mcp/osm-poi/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`nearby_pois`

Find points of interest near a location. Searches OpenStreetMap for POIs within a radius of the given coordinates. Args: lat: Latitude of the centre point (-90 to 90). lon: Longitude of the centre point (-180 to 180). radius_m: Search radius in metres (1–50000, default 500). poi_type: Type of POI to filter by. Examples: "restaurant", "cafe", "hospital", "pharmacy", "hotel", "museum", "supermarket", "park", "ev_charger", "school", "bank", "parking". Omit to return all POI types. max_results: Maximum number of results (1–100, default 20). Returns: Object with count and list of POIs, each with osm_id, name, poi_type, lat, lon, and key OSM tags (address, opening hours, phone, website, etc.).

Parameter	Type	Required	Description
`lat`	number	required	Latitude of the centre point (-90 to 90).
`lon`	number	required	Longitude of the centre point (-180 to 180).
`radius_m`	integer	optional	Search radius in metres (1–50000, default 500). (default: `500`)
`poi_type`	any	optional	Type of POI to filter by. Examples: "restaurant", "cafe", "hospital", "pharmacy", "hotel", "museum", "supermarket", "park", "ev_charger", "school", "bank", "parking". Omit t...
`max_results`	integer	optional	Maximum number of results (1–100, default 20). (default: `20`)

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

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/osm-poi/",
    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': 'nearby_pois'}},
)
print(resp.json())

`search_poi`

Search for POIs by name across OpenStreetMap. Performs a case-insensitive regex search over OSM name tags. Optionally restricted to a specific country. Args: name_query: Name or partial name to search for (e.g. "Starbucks", "IKEA"). country_code: ISO 3166-1 alpha-2 country code to restrict results (e.g. "NO" for Norway, "GB" for UK, "US" for United States). Omit for global search (slower, may time out for common names). max_results: Maximum number of results (1–50, default 20). Returns: Object with count and list of matching POIs, each with osm_id, name, poi_type, lat, lon, and key OSM tags.

Parameter	Type	Required	Description
`name_query`	string	required	Name or partial name to search for (e.g. "Starbucks", "IKEA").
`country_code`	any	optional	ISO 3166-1 alpha-2 country code to restrict results (e.g. "NO" for Norway, "GB" for UK, "US" for United States). Omit for global search (slower, may time out for common names).
`max_results`	integer	optional	Maximum number of results (1–50, default 20). (default: `20`)

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

import httpx

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

`get_poi_details`

Get full OSM tag data for a specific POI. Returns all available metadata for a single OSM element, including opening hours, contact info, accessibility attributes, and more. Args: osm_id: OSM element identifier in the format "type/id", e.g. "node/12345" or "way/67890". Obtained from nearby_pois or search_poi results. Returns: Full POI record with all OSM tags, or {"error": "not_found"} if the element does not exist.

Parameter	Type	Required	Description
`osm_id`	string	required	OSM element identifier in the format "type/id", e.g. "node/12345" or "way/67890". Obtained from nearby_pois or search_poi results.

curl -X POST "https://context.gnist.ai/mcp/osm-poi/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_poi_details", "arguments": {"osm_id": "node/12345"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/osm-poi/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'osm_id': 'node/12345'}, 'name': 'get_poi_details'}},
)
print(resp.json())

`count_pois`

Count POIs within a bounding box. Useful for density analysis, market research, and catchment area studies. Args: min_lat: Southern boundary latitude. min_lon: Western boundary longitude. max_lat: Northern boundary latitude. max_lon: Eastern boundary longitude. poi_type: POI type to count (e.g. "restaurant", "ev_charger"). Omit to count all named POIs. Returns: Object with the count of matching POIs and the queried bbox.

Parameter	Type	Required	Description
`min_lat`	number	required	Southern boundary latitude.
`min_lon`	number	required	Western boundary longitude.
`max_lat`	number	required	Northern boundary latitude.
`max_lon`	number	required	Eastern boundary longitude.
`poi_type`	any	optional	POI type to count (e.g. "restaurant", "ev_charger"). Omit to count all named POIs.

curl -X POST "https://context.gnist.ai/mcp/osm-poi/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "count_pois", "arguments": {"min_lat": 59.91, "min_lon": 10.75, "max_lat": 59.91, "max_lon": 10.75}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/osm-poi/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'max_lat': 59.91,
                          'max_lon': 10.75,
                          'min_lat': 59.91,
                          'min_lon': 10.75},
            'name': 'count_pois'}},
)
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/osm-poi/" \
  -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/osm-poi/",
    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

Search then retrieve
Use search_poi to find items, then get_poi_details to get full details. This two-step pattern is common for exploring data before drilling down.

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

FAQ

What data does OpenStreetMap POI provide?

Points of interest from OpenStreetMap — restaurants, shops, landmarks, and amenities. It exposes 5 tools: nearby_pois, search_poi, get_poi_details, count_pois, 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 OpenStreetMap POI API return?

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