Geography

Data source: GeoNames.org

REST Bridge Endpoint https://context.gnist.ai/rest/geonames/

Authentication

All requests require a Gnist-API-Key header (or api_key query parameter).

Free tier: 100 calls/day. Get your API key.

Tools (7)

search_cities
get_city
get_countries
get_country
search_timezones
get_timezone
report_feedback

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)

Request Body

{
  "query": "example"
}

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

Request Body

{
  "geonameid": 1
}

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.

Request Body

{
  "query": "example"
}

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

Request Body

{
  "iso_code": "example"
}

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)

Request Body

{
  "query": "example"
}

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

Request Body

{
  "timezone_id": "example"
}

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")

Request Body

{
  "feedback": "example"
}

Quick Start

Shell

curl -X POST "https://context.gnist.ai/rest/geonames/search_cities" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"query": "example"}'

Python

import httpx

resp = httpx.post(
    "https://context.gnist.ai/rest/geonames/search_cities",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={
  "query": "example"
},
)
print(resp.json())

Related Toolkits (Geography)

OpenStreetMap POI

Points of interest from OpenStreetMap — restaurants, shops, landmarks, and amenities.

US County Data

US county-level data — population, area, FIPS codes, and county seats for ~200 US counties.

Nominatim Geocoding

Forward and reverse geocoding — address to coordinates and coordinates to address.

Resources

Toolkit Overview

Landing page with health status and quick start.

Tool Schemas (JSON)

Full input/output JSON schemas for all tools.

Developer Quickstart

Get from zero to your first API call in under two minutes.

Get an API Key

Free tier: 100 calls/day. No credit card required.