# Location and Timezone API

> City search and geocoding API + hosted MCP for AI agents and astrology apps. Connect Claude Code, Cursor, VS Code in seconds, no local setup. 7,000+ cities across 227 countries. Returns latitude, longitude, IANA timezone, and DST-aware UTC offset. The location layer for birth chart forms, horoscope apps, event planners, and any feature that needs place-to-coordinates resolution.

Geocoding autocomplete with coordinates and timezone for astrology apps

- Product page: https://roxyapi.com/products/location-api
- OpenAPI spec: https://roxyapi.com/api/v2/location/openapi.json
- Remote MCP server: https://roxyapi.com/mcp/location
- Authentication: `X-API-Key` header on every request
- Pricing: https://roxyapi.com/pricing (all domains included in every plan)

## Stats

- cities: 7,000+
- countries: 227
- latency: <50ms

## Features

- City autocomplete search across 7,000+ cities worldwide, sorted by relevance and population
- Latitude, longitude, IANA timezone, and UTC offset in every result for direct use in astrology APIs
- Global coverage across 227 countries with ISO 3166 codes
- DST-aware UTC offset that adjusts automatically for daylight saving time
- Fully offline dataset with sub-5ms response times, no external geocoding API dependencies
- Response fields map directly to astrology API parameters for seamless integration

## Use Cases

- Birth chart location picker: autocomplete city search that auto-fills latitude, longitude, and timezone
- Event location for transits: get coordinates and timezone for planetary transit and panchang calculations
- Timezone conversion: look up IANA timezone and current UTC offset for any city worldwide
- Country and city directory: browse all 227 countries and their cities for location dropdowns and filters

## FAQ

### How do I turn a birth city into latitude and longitude?

Send a city name to the location API and get back precise latitude and longitude in one call. The dataset covers 7,000+ cities across 227 countries, ranked so the largest matching place leads. This is city-level resolution built for birth and event forms, not street addresses. The coordinates drop straight into every birth chart, kundli, panchang, and forecast request, all under one API key with all 12 spiritual domains included at one flat price.

### How do I get the correct IANA timezone for a birth place?

Every result from the location API carries the IANA timezone for that place, such as Asia/Kolkata, Europe/Berlin, or America/New_York. That single value is what the chart and panchang endpoints need to anchor a reading to true local time. You can read it through the typed SDKs for TypeScript, Python, or PHP, or fetch it agent-side through our Remote MCP server with no local setup and no Docker. One lookup gives you coordinates and timezone together.

### How does city autocomplete work for a birth data form?

Wire a text input to the location API and each keystroke returns ranked city matches in milliseconds, fast enough for live typeahead. Typing ber surfaces Berlin, Bern, and Bergen, most likely first. Selecting one suggestion fills the entire location step at once: city, country, coordinates, and timezone. It is the setup layer that feeds the rest of the platform, and our drop-in UI components and WordPress plugin let you ship that picker without building it from scratch.

### How do I handle daylight saving time in birth charts?

Pass the IANA timezone from the location API into any chart endpoint and daylight saving is handled for you. The chart endpoints resolve that identifier to the offset that was actually in effect on the birth date, so a January New York birth resolves correctly and a July birth does too. This removes the classic bug where a summer offset gets piped into a winter chart and quietly shifts every house. Accuracy at this layer is why one location call protects every downstream reading.

### How do I build a country and city picker for global signups?

The location API ships a full directory: all 227 countries with their ISO codes, plus the cities in each one with coordinates and timezone already attached. Use it to power country dropdowns and dependent city lists for a worldwide audience without sourcing or cleaning your own geo data. Activation is instant, so the directory is live the moment you get your key. The same directory is reachable through the typed SDKs and our Remote MCP server for AI agents.

### Why use this instead of stitching together a separate geocoding service?

The location API is the front door to the whole RoxyAPI platform: the same key that resolves a city also runs all 12 spiritual domains, from Western and Vedic astrology to numerology, tarot, and forecast. You get coordinates and timezone in the exact shape the chart endpoints expect, so there is no glue code between geocoding and calculation. Pricing is flat and predictable with no per-call geocoding bill, and discovery surfaces like AGENTS.md and llms.txt make the whole platform easy for agents to find and use.

## Endpoints

- `GET /api/v2/location/search` Search cities worldwide - Geocoding autocomplete with coordinates and timezone
- `GET /api/v2/location/countries` List all countries - ISO codes and city coverage
- `GET /api/v2/location/countries/{iso2}` Get cities in a country - Geocoding directory sorted by population

### Location and Timezone (`/location/`)
- `GET /location/search?q={city}` — City search. Paginated envelope: `{ total, limit, offset, cities: [...] }`. Each city has `city`, `province`, `country`, `iso2`, `latitude`, `longitude`, `timezone` (IANA string, e.g. `"Asia/Kolkata"`), `utcOffset` (decimal hours, DST-adjusted for today), `population`. Chart endpoints accept `timezone` as either the IANA string or `utcOffset` decimal — both work, IANA is preferred because it resolves to the DST-correct offset for the request's `date`. Call first for any coordinate-dependent endpoint.

## Example Response

```
GET /api/v2/location/search?q=Mumbai
```

```json
{
  "total": 1,
  "limit": 10,
  "offset": 0,
  "cities": [
    {
      "city": "Mumbai",
      "province": "Maharashtra",
      "country": "India",
      "iso2": "IN",
      "latitude": 19.07283,
      "longitude": 72.88261,
      "timezone": "Asia/Kolkata",
      "utcOffset": 5.5,
      "population": 12691836
    }
  ]
}
```

## SDK Quick Start

```typescript
// npm install @roxyapi/sdk
import { createRoxy } from '@roxyapi/sdk';
const roxy = createRoxy(process.env.ROXY_API_KEY!);
const { data, error } = await roxy.location.searchCities({ query: { q: 'Mumbai' } });
```

```python
# pip install roxy-sdk
import os
from roxy_sdk import create_roxy
roxy = create_roxy(api_key=os.environ["ROXY_API_KEY"])
result = roxy.location.search_cities(q="Mumbai")
```

```php
// composer require roxyapi/sdk (PHP 8.2+, built on Saloon)
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->location->searchCities(q: 'Mumbai');
```

Method names come from OpenAPI `operationId` (camelCase in TS and PHP, snake_case in Python). TS returns `{ data, error, response }` — check `error` first. Python raises `RoxyAPIError`; PHP throws `RoxyApiException` (catch and switch on `$e->errorCode`).

## MCP Tool Naming

Each REST endpoint has a matching MCP tool on `https://roxyapi.com/mcp/location`. Tool name convention is `{http_method_lowercase}_{path_with_slashes_as_underscores_kebab_replaced_with_underscores_braces_stripped}`:

```
GET  /location/search                         -> get_location_search
GET  /location/countries                      -> get_location_countries
GET  /location/countries/{iso2}               -> get_location_countries_iso2
```

`tools/list` is free and public (no auth). `tools/call` requires `X-API-Key` (same billing as REST — 1 request per call).

## Error Contract

Success returns clean JSON, no wrapper. Errors return `{ "error": string, "code": string }`. Switch on `code` (stable):

- `validation_error` (400, returns `issues[]` with all field errors at once)
- `api_key_required` (401), `invalid_api_key` (401)
- `subscription_inactive` (403), `subscription_not_found` (404)
- `not_found` (404; PATH-routing 404s carry a fuzzy `suggestion` field)
- `rate_limit_exceeded` (429)
- `internal_error` (500)

Do not retry on 4xx. Do retry on 429 and 5xx with exponential backoff.

## Full Reference

For complete request and response schemas, fetch the OpenAPI spec at https://roxyapi.com/api/v2/location/openapi.json. Master agent manifest at https://roxyapi.com/llms.txt. Execution playbook at https://roxyapi.com/AGENTS.md.