canonical: https://jentic.com/apis/nytimes.com/geographic-api # Nytimes Geographic API The New York Times Geographic API extends the NYT Semantic API with a linked-data layer that resolves location concepts in the NYT controlled vocabulary against external geographic data sources. A single /query.json endpoint accepts a place name or NYT geo concept identifier and returns enriched location records with coordinates, geo facets, and references to the NYT articles tagged with that location. It is designed for agents that need to disambiguate place names mentioned in NYT coverage and link them to consistent geographic identifiers. ## For AI agents Resolve place names against the NYT geographic controlled vocabulary and return linked location data with coordinates and article references. ## Scope Does not provide street-level geocoding, routing, or reverse geocoding for arbitrary addresses - use for resolving place names against the NYT controlled vocabulary only. ## Capabilities - Resolve a place name to its NYT geographic concept identifier - Retrieve linked-data attributes for a NYT location concept including coordinates - Filter geographic concepts by NYT facet vocabulary fields - Surface the NYT articles tagged with a specific location - Page through large result sets via the offset parameter - Disambiguate place names that share spelling but differ in country or region ## Use cases ### Place Disambiguation in News Pipelines Disambiguate place names extracted from text by resolving them against the NYT geographic controlled vocabulary. The /query.json endpoint accepts a place name and returns candidate concepts with country, region, and coordinate context, letting an agent pick the right entity before storing it in a downstream system. Useful for newsroom enrichment, knowledge graphs, and editorial automation. Example prompt: Call /query.json with query='Cambridge' and return the candidate locations with country code so the agent can select the UK city versus the Massachusetts city. ### Article Geographic Linking Build a map-based news browser that lists every NYT article tagged with a chosen location. The Geographic API resolves the place to its NYT concept and the response includes references to associated articles, which can be combined with the Article Search API for full content lookup. Example prompt: Resolve query='Kyiv, Ukraine' via /query.json, extract the geo concept identifier, and return the article references attached to the resolved record. ### Knowledge Graph Enrichment Enrich an internal knowledge graph with NYT-controlled-vocabulary geographic identifiers so that internal location records can be cross-referenced against published NYT coverage. The single /query.json endpoint provides a stable resolver suitable for batch enrichment runs. Example prompt: Iterate through a list of internal city records and call /query.json for each to attach the matching NYT geo concept identifier. ### Agent-Driven Location Lookup via Jentic An AI research agent uses Jentic to resolve a place mentioned in conversation against the NYT geographic vocabulary. Jentic's intent search returns the /query.json operation, the agent loads the schema and executes the lookup without manually reading the NYT semantic linked-data documentation. Example prompt: Search Jentic for 'resolve place name to NYT concept', load the /query.json operation, and execute it with query='Mumbai, India'. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /query.json | Resolve a place name or concept query to NYT geographic records | ## Key resources - **Geographic Concepts** — NYT controlled-vocabulary location records with names, coordinates, and facet metadata. - **Linked Data References** — External identifiers and article references attached to each geographic concept. ## Why Jentic - **Setup:** Wiring the NYT Geographic API by hand means appending your api-key to the query string against api.nytimes.com/svc/semantic/v2/geocodes and handling the vocabulary-lookup request plumbing yourself. Through Jentic you install once, import the NYT Geographic API from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** The Geographic API exposes a single read-only query path with no resource id, so scope the agent to that one operation and leave everything else out. You choose the operations it may call, so it only reaches the endpoint you list. - **Credential handling:** Your NYT api-key is stored once, encrypted, by your own Jentic One instance and injected as the api-key query parameter at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'resolve a place name to an NYT concept' or 'look up the NYT geographic vocabulary', and Jentic returns the query operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **NYT Semantic API** — Parent vocabulary API resolving people, organizations, and descriptors that the Geographic API extends with locations. - **NYT TimesTags API** — Autocomplete-style tag matcher across the full NYT vocabulary including geographies. - **NYT Top Stories API** — Returns top NYT articles by section that can be filtered by geographic tag. ## FAQ ### What authentication does the NYT Geographic API use? The Geographic API uses an API key passed as the api-key query parameter on /query.json. Provision a key at developer.nytimes.com. Through Jentic, the key sits in the vault and is injected at execution time, keeping the secret out of agent context. ### What does the Geographic API return for a place query? Each result is a NYT controlled-vocabulary geographic concept with a stable identifier, place name, country and region facets, latitude and longitude where available, and references to associated NYT articles. It does not return third-party point-of-interest data such as Google Places or OpenStreetMap entries. ### What are the rate limits for the NYT Geographic API? NYT enforces 500 requests per day and 5 requests per minute per API key shared across all NYT developer APIs. Plan batch enrichment runs accordingly and cache concept identifiers since they are stable. ### How do I resolve a place name through Jentic? Search Jentic for 'resolve place name to NYT concept', load the /query.json operation, and execute it with the query parameter set to the place string. The response returns ranked candidate concepts with facets for disambiguation. ### Is the NYT Geographic API free to use? Yes. NYT offers the Geographic API at no cost on the developer portal for non-commercial use within published rate limits. Commercial or high-volume use requires direct contact with the NYT licensing team. ### Can I use this API for full-text geocoding of arbitrary addresses? No. The Geographic API resolves names against the NYT controlled vocabulary, not against a full address geocoder. For street-level geocoding use a dedicated mapping API such as Google Maps or HERE; use the NYT API only when linking text to NYT coverage. ### Can I limit what my agent is allowed to do with the NYT Geographic API? Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use. The NYT Geographic API exposes a single read-only endpoint, GET /query.json, so you can scope the agent to that one place-resolution operation and leave every other API out of reach. Your NYT api-key is held by your own instance and injected only when that permitted call runs, so the agent never sees the secret and cannot reach anything you have not listed.