Timezone and location API with city search and geocoding across 235,000+ cities in 240+ countries, returning latitude, longitude, IANA timezone, and DST-aware UTC offset. Coverage goes down to towns of a few hundred people and every administrative seat, so a rural birthplace resolves as reliably as a capital. The location layer for birth chart forms, horoscope apps, event planners, and any feature that needs place-to-coordinates resolution. Fields map directly to the astrology endpoints, with no separate geocoding service to call or pay for. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs.
3 endpoints. Product page. Typed SDKs in six languages carry every operation below.
GET /api/v2/location/search
Turn a place name into coordinates, an IANA timezone and a DST-aware UTC offset, across 235,000+ cities and towns in 240+ countries. Coverage reaches rural towns of a few hundred people and every administrative seat, so a birthplace outside a major metro resolves as reliably as a capital. Matching is case-insensitive, accent-insensitive and partial, so ber matches Berlin, Bern and Bergen, native scripts are transliterated, and historic names resolve to the current place, so bombay returns Mumbai and peking returns Beijing. Results are ordered by match quality first and population second, so an exactly named small town is never buried under a larger city that merely shares its opening letters. Built for birth chart location pickers, horoscope apps, event scheduling, and any feature that needs place-to-coordinates resolution.
| Parameter | Type | Description |
|---|---|---|
q required query | string | Place to search for, written the way a person would. Accepts a bare city (berlin), a city plus country (berlin germany), a comma-qualified place (richfield, utah), a fully qualified place (richfield, utah, united states), or a historic name (bombay, peking, constantinople). Commas are optional, and a qualifier the dataset spells differently, such as USA for United States, still resolves. Matched against city name, alternate names, state or province, and country. Add the state or country whenever the name is common, since that is what separates the six Springfields, and Richfield, Utah from Richfield, Minnesota. |
limit query | integer | Maximum items to return per page. Range: 1-50, default 10. Default 10. |
offset query | integer | Number of items to skip for pagination. Default 0. Default 0. |
curl "https://roxyapi.com/api/v2/location/search?q=berlin" \
-H "X-API-Key: YOUR_KEY"| Field | Type | Description |
|---|---|---|
total required | number | Number of places matching the query across all pages, not the number returned in this response. Greater than 1 means the name is ambiguous, so show province and country and let the user confirm before using the result for a chart. |
limit required | number | Page size used for this response. |
offset required | number | Number of places skipped. Use with limit to page through results. |
cities required | array of object | Matching places for the current page, best match first. Ordered by match quality, then population within equal quality: an exact name beats a qualified name such as richfield, utah, which beats a name merely starting with the query, which beats an incidental match on state or country. Take the first entry when total is 1, otherwise disambiguate on province and country. |
cities[].city required | string | City name as commonly used. Matches the local or internationally recognized name for the location. |
cities[].province required | string | State, province, canton, or administrative region. Show it whenever more than one result comes back: it is what separates Richfield, Utah from Richfield, Minnesota, and the six US Springfields from each other. Empty for the small number of places with no administrative division recorded. |
cities[].country required | string | Full country name in English. |
cities[].iso2 required | string | ISO 3166-1 alpha-2 country code. Use for filtering cities by country or building country-specific location pickers. |
cities[].latitude required | number | Geographic latitude in decimal degrees (-90 to 90). Pass directly to birth chart, natal chart, horoscope, synastry, transit, kundli, and panchang API endpoints as the latitude parameter. |
cities[].longitude required | number | Geographic longitude in decimal degrees (-180 to 180). Pass directly to astrology, horoscope, and panchang API endpoints alongside latitude. |
cities[].timezone required | string | IANA timezone identifier following the tz database standard (e.g. Europe/Berlin, America/New_York, Asia/Tokyo). Always present. Pass THIS, not the numeric offset, into any chart or panchang request for a past date: the calculation endpoints resolve it to the offset that was actually in force on that date, including historical daylight saving. Also works directly with JavaScript Date, Luxon, day.js, or any date library. |
cities[].utcOffset required | number | UTC offset in decimal hours for TODAY at this place, already adjusted for daylight saving. Convenient for displaying local time now. For a birth date or any past date use the `timezone` field instead, since the offset in force then may differ. Examples: 1 for CET, 2 for CEST, -5 for EST, 5.5 for IST, 5.75 for Nepal. |
cities[].population required | number | Population estimate for the place. Breaks ties between results of equal match quality, so among several places matching equally well the largest leads. It never outranks a better match, which is why a small town still wins when its name is typed exactly. May be 0 for a hamlet or administrative seat that carries no published figure. |
{
"total": 3,
"limit": 10,
"offset": 0,
"cities": [
{
"city": "Berlin",
"province": "Berlin",
"country": "Germany",
"iso2": "DE",
"latitude": 52.52,
"longitude": 13.405,
"timezone": "Europe/Berlin",
"utcOffset": 1,
"population": 3644826
}
]
}GET /api/v2/location/countries
Returns every country with ISO 3166-1 alpha-2 and alpha-3 codes, plus the number of searchable cities per country. Use this endpoint to build country dropdown menus, regional filters, or to check city coverage before querying a birth location. Countries are sorted alphabetically by name. Covers Europe, Americas, Asia, Middle East, Africa, and Oceania.
| Parameter | Type | Description |
|---|---|---|
limit query | integer | Maximum items to return per page. Range: 1-250, default 50. Default 50. |
offset query | integer | Number of items to skip for pagination. Default 0. Default 0. |
curl "https://roxyapi.com/api/v2/location/countries" \
-H "X-API-Key: YOUR_KEY"| Field | Type | Description |
|---|---|---|
total required | number | Total number of countries with at least one place in the dataset. |
limit required | number | Page size used for this response. |
offset required | number | Number of countries skipped. Use with limit for pagination. |
countries required | array of object | Countries for the current page, sorted alphabetically by name. |
countries[].name required | string | Full country name in English. Use for display in location pickers and dropdown menus. |
countries[].iso2 required | string | ISO 3166-1 alpha-2 country code. Use as the identifier when fetching cities for a specific country via the /countries/{iso2} endpoint. |
countries[].iso3 required | string | ISO 3166-1 alpha-3 country code. Three-letter standard used in international data exchange. |
countries[].cityCount required | number | Number of searchable places in this country, including small towns and administrative seats. Useful for showing coverage in a UI or sizing a dependent city dropdown. |
{
"total": 246,
"limit": 50,
"offset": 0,
"countries": [
{
"name": "Germany",
"iso2": "DE",
"iso3": "DEU",
"cityCount": 11894
}
]
}GET /api/v2/location/countries/{iso2}
Returns all cities for a specific country, identified by ISO 3166-1 alpha-2 code (e.g. DE for Germany, FR for France, GB for United Kingdom, US for United States). Each city includes geographic coordinates, IANA timezone, and DST-aware UTC offset for direct use in astrology birth chart, horoscope, transit, and panchang calculations. Cities sorted by population with the largest metropolitan areas first.
| Parameter | Type | Description |
|---|---|---|
iso2 required path | string | ISO 3166-1 alpha-2 country code, case-insensitive. Common codes: DE (Germany), FR (France), GB (United Kingdom), US (United States), ES (Spain), IT (Italy), NL (Netherlands), IN (India), BR (Brazil), JP (Japan). |
limit query | integer | Maximum items to return per page. Range: 1-100, default 20. Default 20. |
offset query | integer | Number of items to skip for pagination. Default 0. Default 0. |
curl "https://roxyapi.com/api/v2/location/countries/DE" \
-H "X-API-Key: YOUR_KEY"| Field | Type | Description |
|---|---|---|
total required | number | Total number of places available for this country across all pages. |
limit required | number | Page size used for this response. |
offset required | number | Number of cities skipped. Use with limit for pagination. |
cities required | array of object | Cities for the current page, sorted by population (largest first). |
cities[].city required | string | City name as commonly used. Matches the local or internationally recognized name for the location. |
cities[].province required | string | State, province, canton, or administrative region. Show it whenever more than one result comes back: it is what separates Richfield, Utah from Richfield, Minnesota, and the six US Springfields from each other. Empty for the small number of places with no administrative division recorded. |
cities[].country required | string | Full country name in English. |
cities[].iso2 required | string | ISO 3166-1 alpha-2 country code. Use for filtering cities by country or building country-specific location pickers. |
cities[].latitude required | number | Geographic latitude in decimal degrees (-90 to 90). Pass directly to birth chart, natal chart, horoscope, synastry, transit, kundli, and panchang API endpoints as the latitude parameter. |
cities[].longitude required | number | Geographic longitude in decimal degrees (-180 to 180). Pass directly to astrology, horoscope, and panchang API endpoints alongside latitude. |
cities[].timezone required | string | IANA timezone identifier following the tz database standard (e.g. Europe/Berlin, America/New_York, Asia/Tokyo). Always present. Pass THIS, not the numeric offset, into any chart or panchang request for a past date: the calculation endpoints resolve it to the offset that was actually in force on that date, including historical daylight saving. Also works directly with JavaScript Date, Luxon, day.js, or any date library. |
cities[].utcOffset required | number | UTC offset in decimal hours for TODAY at this place, already adjusted for daylight saving. Convenient for displaying local time now. For a birth date or any past date use the `timezone` field instead, since the offset in force then may differ. Examples: 1 for CET, 2 for CEST, -5 for EST, 5.5 for IST, 5.75 for Nepal. |
cities[].population required | number | Population estimate for the place. Breaks ties between results of equal match quality, so among several places matching equally well the largest leads. It never outranks a better match, which is why a small town still wins when its name is typed exactly. May be 0 for a hamlet or administrative seat that carries no published figure. |
{
"total": 11894,
"limit": 50,
"offset": 0,
"cities": [
{
"city": "Berlin",
"province": "Berlin",
"country": "Germany",
"iso2": "DE",
"latitude": 52.52,
"longitude": 13.405,
"timezone": "Europe/Berlin",
"utcOffset": 1,
"population": 3644826
}
]
}Hi, I am Rosie, your guide to the RoxyAPI insight tools.
Ask me to read your birth chart, pull a card, or map your numbers, and I will interpret what it means for you. Unlike most AIs, I never make the numbers up: every reading runs on real, verified calculations. Curious about the API, pricing, or docs instead? Ask me that too.