Tutorial: GeoNames - Gnist Context

Geography

Data source: GeoNames.org

Overview

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

Tools (7)

`search_cities`

Search for cities by name. Args: query: City name or partial name to search for. country_code: Optional ISO-3166 country code to restrict the search (e.g. 'NO', 'US'). limit: Maximum number of results (default 10). Returns: Dictionary with 'data' list of matching cities, each with name, country_code, latitude, longitude, population, timezone, and geonameid.

Parameter	Type	Required	Description
`query`	string	required
`country_code`	any	optional
`limit`	integer	optional	(default: `10`)

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

import httpx

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

`get_city`

Get a city by its GeoNames ID. Args: geonameid: The GeoNames ID of the city. Returns: Dictionary with city details, or an error if not found.

Parameter	Type	Required	Description
`geonameid`	integer	required

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

import httpx

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

`get_countries`

List all countries. Returns: Dictionary with 'data' list of all countries, each with iso_code, country_name, capital, population, continent, currency_code, and languages.

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

import httpx

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

`get_country`

Get a country by its ISO-3166 code. Args: iso_code: Two-letter ISO-3166 country code (e.g. 'NO', 'US', 'DE'). Returns: Dictionary with country details, or an error if not found.

Parameter	Type	Required	Description
`iso_code`	string	required

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

import httpx

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

`search_timezones`

Search for timezones by ID or filter by country. Args: query: Optional partial timezone ID to search for (e.g. 'Europe'). country_code: Optional ISO-3166 country code to filter by (e.g. 'NO'). limit: Maximum number of results (default 10). Returns: Dictionary with 'data' list of matching timezones, each with timezone_id, country_code, gmt_offset_jan, dst_offset_jul, and raw_offset.

Parameter	Type	Required	Description
`query`	any	optional
`country_code`	any	optional
`limit`	integer	optional	(default: `10`)

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

import httpx

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

`get_timezone`

Get a timezone by its IANA timezone ID. Args: timezone_id: IANA timezone ID (e.g. 'Europe/Oslo', 'America/New_York'). Returns: Dictionary with timezone details, or an error if not found.

Parameter	Type	Required	Description
`timezone_id`	string	required

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

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/geonames/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'timezone_id': '12345'}, 'name': 'get_timezone'}},
)
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/geonames/" \
  -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/geonames/",
    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_cities to find items, then get_city 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 GeoNames provide?

Geographical database — place names, coordinates, populations, and administrative divisions. It exposes 7 tools: search_cities, get_city, get_countries, get_country, search_timezones, get_timezone, 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 GeoNames API return?

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

Next Steps

Interactive Playground

Try tools in your browser — no setup required.

Full Reference

Complete docs for all 7 tools.

Getting Started with GeoNames