canonical: https://jentic.com/apis/geodatasource.com/geodatasource

# GeoDataSource Location Search

Jentic publishes the only available OpenAPI specification for GeoDataSource Location Search, keeping it validated and agent-ready. GeoDataSource is a lightweight reverse-geocoding service that accepts a latitude and longitude and returns the city, region, and country for that coordinate, in either JSON or XML. The single /city endpoint is intended as a fast, low-friction lookup for analytics dashboards, simple location enrichment, and fallback paths in larger geocoding stacks. Authentication and other operational details are handled per the vendor's own documentation rather than through the spec.

## For AI agents

Reverse-geocode a latitude and longitude pair to a city, region, and country via a single lightweight lookup endpoint.

## Scope

Does not handle forward geocoding, routing, or street-level address resolution - use for coordinate-to-city reverse lookup only.

## Capabilities

- Convert latitude and longitude into a city name with /city
- Receive country and region context for a coordinate alongside the city
- Choose JSON or XML response format for downstream consumers
- Use as a low-cost fallback when a primary geocoder rate-limits or fails
- Enrich session logs with a coordinate-derived city name for analytics dashboards

## Use cases

### Analytics Dashboard Enrichment

Product teams enrich web analytics events that already contain a coordinate (from IP geolocation or browser geolocation) with a human-readable city name. The /city endpoint converts each coordinate to a city/region/country triple and the values feed directly into a BI dashboard slice without needing a heavy geocoding stack.

Example prompt: For each session in the events table, call /city with the lat/lng and store the returned city name in the enriched analytics row

### Fallback Geocoder

Engineering teams running a primary geocoder (Geocodio, Google, HERE) want a cheap fallback when the primary rate-limits or fails. GeoDataSource's single endpoint is dependency-light and returns the coarse city/region/country needed to keep most user-facing flows alive while the primary cools down.

Example prompt: On a 429 response from the primary geocoder, retry the lookup against /city and use the city/region/country result to keep the request flowing

### Compliance Region Routing

Apps with regional compliance requirements decide which data residency region to use based on a user's country. /city returns the country alongside the city for a given coordinate, enabling a routing layer to choose an EU vs US backend without standing up a full geocoding service.

Example prompt: On signup, call /city for the user's coordinate and route the account to the EU backend when the response country is in the EEA

### AI Agent Location Context

An AI agent answering location-shaped questions can call GeoDataSource through Jentic for a quick city lookup. Because the /city endpoint takes only lat/lng, the agent can produce a 'this user is in Paris, FR' style answer with a single search-load-execute cycle.

Example prompt: Search Jentic for 'reverse geocode a coordinate to city', execute /city with 48.8566,2.3522, and return 'Paris, Île-de-France, France' to the chat thread

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/city` | Reverse-geocode a latitude and longitude to a city, region, and country |

## Key resources

- **City Lookup** — Reverse-geocode a coordinate pair to a city, region, and country

## Why Jentic

- **Setup:** Wiring the GeoDataSource Location Search API by hand means constructing the /city request with latitude, longitude, and format parameters and parsing the reverse-lookup response yourself. Through Jentic you install once, import GeoDataSource from the API Directory, store any required credential once, and your agent calls it.
- **Permission scoping:** GeoDataSource exposes a single reverse-lookup operation that takes its coordinates in the query string, so scope the agent to just the operation it needs. You choose the operations it may call, so nothing beyond coordinate-to-city lookup runs unless you add it.
- **Credential handling:** Any GeoDataSource credential is stored once, encrypted, by your own Jentic One instance and attached to the /city call at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'reverse geocode a coordinate to a city', and Jentic returns the /city operation with its parameter schema for latitude, longitude, and format, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **OpenCage** — Worldwide forward and reverse geocoding aggregating multiple open data sources
- **Positionstack** — Forward and reverse geocoding API with bulk and single-request modes
- **HERE Maps** — Maps, routing, and traffic to pair with the city result for richer location experiences

## FAQ

### Why is there no official OpenAPI spec for GeoDataSource Location Search?

GeoDataSource does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call GeoDataSource Location Search via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the GeoDataSource API use?

The OpenAPI spec does not declare a security scheme - authentication is handled per the vendor's web-service documentation, typically a key passed as a query parameter on the call. When integrating through Jentic, store any required key in the vault so it is injected at execution time.

### Can I get JSON output from GeoDataSource?

Yes. The /city endpoint supports both JSON and XML output formats - request JSON with the appropriate format query parameter to receive a structured response with city, region, and country fields.

### What are the rate limits for the GeoDataSource API?

The OpenAPI spec does not declare explicit rate limits. GeoDataSource meters usage by plan on its website - for production workloads, batch lookups, cache the city result per coordinate, and confirm the plan ceiling before backfilling large coordinate tables.

### How do I reverse-geocode a coordinate through Jentic?

Run pip install jentic, search Jentic for 'reverse geocode a coordinate to city', and call /city with the latitude and longitude as query parameters. The response contains the city, region, and country corresponding to the point.

### When should I choose GeoDataSource over a full geocoder?

Choose GeoDataSource when you only need a coarse city/region/country lookup at low cost - for analytics enrichment, fallback paths, or compliance routing. For street-level forward geocoding, address validation, or routing, use a full geocoder like Geocodio or HERE.

### Can I limit what my agent is allowed to do with the GeoDataSource API?

Yes. Because GeoDataSource exposes only a single reverse-lookup operation, the /city endpoint that turns a latitude and longitude into a city, region, and country, you scope your agent to just that call and nothing else runs. Since Jentic One is self-hosted, your own rules on your instance decide which operations and credentials the agent may use, so you can allow the coordinate-to-city lookup while withholding everything else. Any required GeoDataSource key is stored on your instance and attached to the /city request at execution time rather than exposed to the agent.