canonical: https://jentic.com/apis/api-ninjas.com/api-ninjas-city

# API Ninjas City API

Jentic publishes the only available OpenAPI specification for API Ninjas City API, keeping it validated and agent-ready. The endpoint returns city records including name, country, latitude and longitude, population, and capital status, covering over 50,000 cities on the free plan and over 5,000,000 cities, towns, and villages on premium. It is a single-endpoint lookup that supports filtering by name, country, minimum and maximum population, and limit. Authentication is by X-Api-Key header.

## For AI agents

Look up city records with name, country, coordinates, population, and capital status by querying API Ninjas' single /city endpoint.

## Scope

Does not handle street-level geocoding, reverse geocoding from coordinates, or routing - use for city-level lookup of name, country, coordinates, and population only.

## Capabilities

- Look up a city by name and receive its country, coordinates, population, and capital flag
- Filter cities by country code to surface only matches inside a chosen jurisdiction
- Constrain results to a population range using min_population and max_population
- Limit the number of returned records with the limit parameter for pagination control
- Cross-reference unfamiliar place names in agent text against a structured city database

## Use cases

### Geocode a City Name in Agent Output

When an agent generates content that mentions a city, it can call /city with the city name to confirm the city exists, retrieve its coordinates, and ground later steps in real geographic data. This is a lightweight alternative to a full geocoding service for cases where only a city-level resolution is required.

Example prompt: Call GET /city with name=Lisbon and read the returned latitude, longitude, and population fields

### Filter Cities by Population

Generate a list of mid-sized cities in a country for a market-research, travel, or content workflow by calling /city with a country code, min_population, and max_population. The endpoint returns each matching city with its coordinates, which can then feed a map widget or downstream analytics step. Limit controls how many are returned per call.

Example prompt: Call /city with country=FR min_population=100000 max_population=500000 limit=20 to list mid-sized French cities

### Capital City Lookup

Build a quiz or factual lookup feature that returns the capital of a country by querying /city with the country code and filtering for the is_capital flag in the response. The same call surfaces population and coordinates, which is enough to render a single-card answer in a chat or knowledge experience.

Example prompt: Call /city with country=PT and pick the record where is_capital is true to surface Lisbon's coordinates and population

### Agent Integration via Jentic

An AI agent built on Jentic can search for the API Ninjas city lookup operation by intent and execute it without holding the X-Api-Key in agent context. Jentic's your Jentic One instance keeps the credential isolated, which matters when many agents share a single API Ninjas key for low-cost data lookups.

Example prompt: Use Jentic search for 'look up a city by name', load the /city operation, execute it with name=Buenos Aires, and read the latitude, longitude, and population from the response

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /city | Look up cities by name, country, or population range |

## Key resources

- **City** — Single GET endpoint returning city records with name, country, coordinates, population, and capital flag

## Why Jentic

- **Setup:** Wiring the API Ninjas City API by hand means handling its API-key request header, targeting the v1 host, and mapping the single city lookup with its query parameters yourself. Through Jentic you install once, import API Ninjas City from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** The City API exposes a single lookup that takes its filters as query parameters rather than a resource id in the URL path, so you limit the agent to that one city-lookup operation. It reads city name, country, coordinates, and population and does nothing else.
- **Credential handling:** Your API Ninjas key is stored once, encrypted, by your own Jentic One instance and injected as the request header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'look up a city by name', and Jentic returns the matching city operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Geocodio** — Full geocoder that resolves any address to coordinates, not just city centres
- **OpenCage Geocoding** — Forward and reverse geocoding with worldwide coverage
- **ipgeolocation.io** — Resolve IP addresses to city, country, and coordinates

## FAQ

### Why is there no official OpenAPI spec for API Ninjas City API?

API Ninjas does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call API Ninjas City API 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 API Ninjas City API use?

The endpoint requires an API key passed as the X-Api-Key header. When called through Jentic the key is held in your Jentic One instance and a scoped execution token is granted to the agent at call time, never the raw key.

### Can I filter cities by population with the API Ninjas City API?

Yes. GET /city accepts min_population and max_population query parameters which constrain the returned cities to the chosen range. Combine with country to filter inside a single jurisdiction and with limit to cap the number of records returned.

### What are the rate limits for the API Ninjas City API?

API Ninjas applies a per-account monthly request quota that depends on the subscription tier rather than the OpenAPI spec. Check your API Ninjas dashboard for the current monthly ceiling and respect any 429 responses with exponential backoff.

### How do I look up a city through Jentic?

Install the Jentic SDK with pip install jentic, search for 'look up a city by name', load the GET /city operation, and execute it with the name and any optional filters such as country or population. Run it through Jentic One, the self-hosted execution layer to get a Jentic agent key.

### How many cities does the API Ninjas City API cover?

The free plan covers over 50,000 cities. Premium plans cover more than 5,000,000 cities, towns, and villages, which is enough for fine-grained address-level lookups. Use the country and population filters to keep result sets manageable.

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

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use, and this API exposes only a single city-lookup operation, so you can restrict the agent to that one call. That operation reads city name, country, coordinates, and population through query-parameter filters and does nothing else, so a scoped agent cannot write data or reach any other endpoint. You keep the API Ninjas key in your own instance and grant the agent access only to the city lookup you approve.