logo
API docs by Redocly

GeoDB Cities API (1.0.0)

Download OpenAPI specification:

License: Creative Commons Attribution 3.0

The GeoDB API focuses on getting global places and regions. Easily obtain country, region, and place data for use in your apps!

Key Features

  • Filter places by name prefix, country, location, time-zone, and even minimum population.
  • Sort places by name, country code, elevation, and population — or any combination of these.
  • Get all country regions.
  • Get all places in a given country or region.
  • Display results in multiple languages.
  • RESTful API adheres to industry best-practices, including HATEOAS-style links to facilitate paging results.
  • Backed by cloud-based load-balanced infrastructure.
  • Data is periodically refreshed from GeoNames and WikiData.

Important Notes

Since the database is periodically updated, this may very rarely result in certain places being marked as deleted (e.g., duplicates removed).

By default, endpoints returning place data will exclude deleted places. However, if you're paging through results and want to avoid unexpected changes due to deletions, you can specify:

  • includeDeleted=SINCE_YESTERDAY
  • or includeDeleted=SINCE_LAST_WEEK (if you're extra cautious)

Useful Resources

SDKs

Documentation & License

Geo

Geo Endpoints

Find admin divisions

Find administrative divisions, filtering by optional criteria. If no criteria are set, you will get back all known divisions.

Authorizations:
UserSecurity
query Parameters
location
string

Only places near this location. Latitude/longitude in ISO-6709 format: ±DD.DDDD±DDD.DDDD

radius
integer <int32>

The location radius within which to find places

distanceUnit
string
Default: "MI"

The unit of distance: MI | KM

countryIds
string

Only places in these countries (comma-delimited country codes or WikiData ids)

excludedCountryIds
string

Only places NOT in these countries (comma-delimited country codes or WikiData ids)

minPopulation
integer <int32>

Only places having at least this population

maxPopulation
integer <int32>

Only places having no more than this population

namePrefix
string

Only entities whose names start with this prefix. If languageCode is set, the prefix will be matched on the name as it appears in that language.

namePrefixDefaultLangResults
boolean
Default: true

When name-prefix matching, whether or not to match on names in the default language if a non-default languageCode is set.

timeZoneIds
string

Only places in these time-zones (comma-delimited)

asciiMode
boolean
Default: false

Display results using ASCII characters

hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

languageCode
string

Display results in this language

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

sort
string

How to sort places. Format: ±SORT_FIELD,±SORT_FIELD where SORT_FIELD = countryCode | elevation | name | population

includeDeleted
string
Default: "NONE"

Whether to include any divisions marked deleted: ALL | SINCE_YESTERDAY | SINCE_LAST_WEEK | NONE

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Get admin division details

Get administrative division details such as location coordinates, population, and elevation above sea-level (if available).

Authorizations:
UserSecurity
path Parameters
divisionId
required
string

An admin-division id (either native 'id' or 'wikiDataId')

query Parameters
asciiMode
boolean
Default: false

Display results using ASCII characters

languageCode
string

Display results in this language

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ]
}

Find cities near division

Find cities near the given administrative division, filtering by optional criteria. If no criteria are set, you will get back all known cities.

Authorizations:
UserSecurity
path Parameters
divisionId
required
string

An admin-division id (either native 'id' or 'wikiDataId')

query Parameters
radius
integer <int32>

The location radius within which to find places

distanceUnit
string
Default: "MI"

The unit of distance: MI | KM

countryIds
string

Only places in these countries (comma-delimited country codes or WikiData ids)

excludedCountryIds
string

Only places NOT in these countries (comma-delimited country codes or WikiData ids)

minPopulation
integer <int32>

Only places having at least this population

maxPopulation
integer <int32>

Only places having no more than this population

namePrefix
string

Only entities whose names start with this prefix. If languageCode is set, the prefix will be matched on the name as it appears in that language.

namePrefixDefaultLangResults
boolean
Default: true

When name-prefix matching, whether or not to match on names in the default language if a non-default languageCode is set.

timeZoneIds
string

Only places in these time-zones (comma-delimited)

types
string

Only cities for these types (comma-delimited): ADM2 | CITY

asciiMode
boolean
Default: false

Display results using ASCII characters

hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

languageCode
string

Display results in this language

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

sort
string

How to sort places. Format: ±SORT_FIELD,±SORT_FIELD where SORT_FIELD = countryCode | elevation | name | population

includeDeleted
string
Default: "NONE"

Whether to include any divisions marked deleted: ALL | SINCE_YESTERDAY | SINCE_LAST_WEEK | NONE

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Find admin divisions near division

Find administrative divisions near the given division, filtering by optional criteria. If no criteria are set, you will get back all known divisions.

Authorizations:
UserSecurity
path Parameters
divisionId
required
string

An admin-division id (either native 'id' or 'wikiDataId')

query Parameters
radius
integer <int32>

The location radius within which to find places

distanceUnit
string
Default: "MI"

The unit of distance: MI | KM

countryIds
string

Only places in these countries (comma-delimited country codes or WikiData ids)

excludedCountryIds
string

Only places NOT in these countries (comma-delimited country codes or WikiData ids)

minPopulation
integer <int32>

Only places having at least this population

maxPopulation
integer <int32>

Only places having no more than this population

namePrefix
string

Only entities whose names start with this prefix. If languageCode is set, the prefix will be matched on the name as it appears in that language.

namePrefixDefaultLangResults
boolean
Default: true

When name-prefix matching, whether or not to match on names in the default language if a non-default languageCode is set.

timeZoneIds
string

Only places in these time-zones (comma-delimited)

asciiMode
boolean
Default: false

Display results using ASCII characters

hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

languageCode
string

Display results in this language

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

sort
string

How to sort places. Format: ±SORT_FIELD,±SORT_FIELD where SORT_FIELD = countryCode | elevation | name | population

includeDeleted
string
Default: "NONE"

Whether to include any divisions marked deleted: ALL | SINCE_YESTERDAY | SINCE_LAST_WEEK | NONE

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Find places near division

Find places near the given administrative division, filtering by optional criteria. If no criteria are set, you will get back all known places.

Authorizations:
UserSecurity
path Parameters
divisionId
required
string

An admin-division id (either native 'id' or 'wikiDataId')

query Parameters
radius
integer <int32>

The location radius within which to find places

distanceUnit
string
Default: "MI"

The unit of distance: MI | KM

countryIds
string

Only places in these countries (comma-delimited country codes or WikiData ids)

excludedCountryIds
string

Only places NOT in these countries (comma-delimited country codes or WikiData ids)

minPopulation
integer <int32>

Only places having at least this population

maxPopulation
integer <int32>

Only places having no more than this population

namePrefix
string

Only entities whose names start with this prefix. If languageCode is set, the prefix will be matched on the name as it appears in that language.

namePrefixDefaultLangResults
boolean
Default: true

When name-prefix matching, whether or not to match on names in the default language if a non-default languageCode is set.

timeZoneIds
string

Only places in these time-zones (comma-delimited)

types
string

Only places for these types (comma-delimited): ADM2 | CITY | ISLAND

asciiMode
boolean
Default: false

Display results using ASCII characters

hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

languageCode
string

Display results in this language

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

sort
string

How to sort places. Format: ±SORT_FIELD,±SORT_FIELD where SORT_FIELD = countryCode | elevation | name | population

includeDeleted
string
Default: "NONE"

Whether to include any divisions marked deleted: ALL | SINCE_YESTERDAY | SINCE_LAST_WEEK | NONE

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Find cities

Find cities, filtering by optional criteria. If no criteria are set, you will get back all known cities.

Authorizations:
UserSecurity
query Parameters
location
string

Only places near this location. Latitude/longitude in ISO-6709 format: ±DD.DDDD±DDD.DDDD

radius
integer <int32>

The location radius within which to find places

distanceUnit
string
Default: "MI"

The unit of distance: MI | KM

countryIds
string

Only places in these countries (comma-delimited country codes or WikiData ids)

excludedCountryIds
string

Only places NOT in these countries (comma-delimited country codes or WikiData ids)

minPopulation
integer <int32>

Only places having at least this population

maxPopulation
integer <int32>

Only places having no more than this population

namePrefix
string

Only entities whose names start with this prefix. If languageCode is set, the prefix will be matched on the name as it appears in that language.

namePrefixDefaultLangResults
boolean
Default: true

When name-prefix matching, whether or not to match on names in the default language if a non-default languageCode is set.

timeZoneIds
string

Only places in these time-zones (comma-delimited)

types
string

Only cities for these types (comma-delimited): ADM2 | CITY

asciiMode
boolean
Default: false

Display results using ASCII characters

hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

languageCode
string

Display results in this language

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

sort
string

How to sort places. Format: ±SORT_FIELD,±SORT_FIELD where SORT_FIELD = countryCode | elevation | name | population

includeDeleted
string
Default: "NONE"

Whether to include any divisions marked deleted: ALL | SINCE_YESTERDAY | SINCE_LAST_WEEK | NONE

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Find cities near city

Find cities near the given city, filtering by optional criteria. If no criteria are set, you will get back all cities within the default radius.

Authorizations:
UserSecurity
path Parameters
cityId
required
string

A city id (either native 'id' or 'wikiDataId')

query Parameters
radius
integer <int32>

The location radius within which to find places

distanceUnit
string
Default: "MI"

The unit of distance: MI | KM

countryIds
string

Only places in these countries (comma-delimited country codes or WikiData ids)

excludedCountryIds
string

Only places NOT in these countries (comma-delimited country codes or WikiData ids)

minPopulation
integer <int32>

Only places having at least this population

maxPopulation
integer <int32>

Only places having no more than this population

namePrefix
string

Only entities whose names start with this prefix. If languageCode is set, the prefix will be matched on the name as it appears in that language.

namePrefixDefaultLangResults
boolean
Default: true

When name-prefix matching, whether or not to match on names in the default language if a non-default languageCode is set.

timeZoneIds
string

Only places in these time-zones (comma-delimited)

types
string

Only cities for these types (comma-delimited): ADM2 | CITY

asciiMode
boolean
Default: false

Display results using ASCII characters

hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

languageCode
string

Display results in this language

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

sort
string

How to sort places. Format: ±SORT_FIELD,±SORT_FIELD where SORT_FIELD = countryCode | elevation | name | population

includeDeleted
string
Default: "NONE"

Whether to include any divisions marked deleted: ALL | SINCE_YESTERDAY | SINCE_LAST_WEEK | NONE

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Find admin divisions near city

Find administrative divisions near the given city, filtering by optional criteria. If no criteria are set, you will get back all divisions within the default radius.

Authorizations:
UserSecurity
path Parameters
cityId
required
string

A city id (either native 'id' or 'wikiDataId')

query Parameters
radius
integer <int32>

The location radius within which to find places

distanceUnit
string
Default: "MI"

The unit of distance: MI | KM

countryIds
string

Only places in these countries (comma-delimited country codes or WikiData ids)

excludedCountryIds
string

Only places NOT in these countries (comma-delimited country codes or WikiData ids)

minPopulation
integer <int32>

Only places having at least this population

maxPopulation
integer <int32>

Only places having no more than this population

namePrefix
string

Only entities whose names start with this prefix. If languageCode is set, the prefix will be matched on the name as it appears in that language.

namePrefixDefaultLangResults
boolean
Default: true

When name-prefix matching, whether or not to match on names in the default language if a non-default languageCode is set.

timeZoneIds
string

Only places in these time-zones (comma-delimited)

asciiMode
boolean
Default: false

Display results using ASCII characters

hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

languageCode
string

Display results in this language

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

sort
string

How to sort places. Format: ±SORT_FIELD,±SORT_FIELD where SORT_FIELD = countryCode | elevation | name | population

includeDeleted
string
Default: "NONE"

Whether to include any divisions marked deleted: ALL | SINCE_YESTERDAY | SINCE_LAST_WEEK | NONE

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Find places near city

Find places near the given city, filtering by optional criteria. If no criteria are set, you will get back all places within the default radius.

Authorizations:
UserSecurity
path Parameters
cityId
required
string

A city id (either native 'id' or 'wikiDataId')

query Parameters
radius
integer <int32>

The location radius within which to find places

distanceUnit
string
Default: "MI"

The unit of distance: MI | KM

countryIds
string

Only places in these countries (comma-delimited country codes or WikiData ids)

excludedCountryIds
string

Only places NOT in these countries (comma-delimited country codes or WikiData ids)

minPopulation
integer <int32>

Only places having at least this population

maxPopulation
integer <int32>

Only places having no more than this population

namePrefix
string

Only entities whose names start with this prefix. If languageCode is set, the prefix will be matched on the name as it appears in that language.

namePrefixDefaultLangResults
boolean
Default: true

When name-prefix matching, whether or not to match on names in the default language if a non-default languageCode is set.

timeZoneIds
string

Only places in these time-zones (comma-delimited)

types
string

Only places for these types (comma-delimited): ADM2 | CITY | ISLAND

asciiMode
boolean
Default: false

Display results using ASCII characters

hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

languageCode
string

Display results in this language

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

sort
string

How to sort places. Format: ±SORT_FIELD,±SORT_FIELD where SORT_FIELD = countryCode | elevation | name | population

includeDeleted
string
Default: "NONE"

Whether to include any divisions marked deleted: ALL | SINCE_YESTERDAY | SINCE_LAST_WEEK | NONE

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Get city details

Get city details such as location coordinates, population, and elevation above sea-level (if available).

Authorizations:
UserSecurity
path Parameters
cityId
required
string

A city id (either native 'id' or 'wikiDataId')

query Parameters
asciiMode
boolean
Default: false

Display results using ASCII characters

languageCode
string

Display results in this language

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ]
}

Get city distance

Get distance from the given city

Authorizations:
UserSecurity
path Parameters
cityId
required
string

A city id (either native 'id' or 'wikiDataId')

query Parameters
toCityId
required
string

Distance to this city

distanceUnit
string
Default: "MI"

The unit of distance: MI | KM

Responses

Response samples

Content type
application/json
{
  • "data": 0.8008281904610115,
  • "errors": [
    ]
}

Get city date-time

Get city date-time

Authorizations:
UserSecurity
path Parameters
cityId
required
string

A city id (either native 'id' or 'wikiDataId')

Responses

Response samples

Content type
application/json
{
  • "data": "2000-01-23T04:56:07.000+00:00",
  • "errors": [
    ]
}

Get city containing region

Get the details for the containing populated place (e.g., its county or other administrative division), including location coordinates, population, and elevation above sea-level (if available).

Authorizations:
UserSecurity
path Parameters
cityId
required
string

A city id (either native 'id' or 'wikiDataId')

query Parameters
asciiMode
boolean
Default: false

Display results using ASCII characters

languageCode
string

Display results in this language

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ]
}

Get city time

Get city time

Authorizations:
UserSecurity
path Parameters
cityId
required
string

A city id (either native 'id' or 'wikiDataId')

Responses

Response samples

Content type
application/json
{
  • "data": "data",
  • "errors": [
    ]
}

Find countries

Find countries, filtering by optional criteria. If no criteria are set, you will get back all known countries.

Authorizations:
UserSecurity
query Parameters
currencyCode
string

Only countries supporting this currency

namePrefix
string

Only entities whose names start with this prefix. If languageCode is set, the prefix will be matched on the name as it appears in that language.

namePrefixDefaultLangResults
boolean
Default: true

When name-prefix matching, whether or not to match on names in the default language if a non-default languageCode is set.

asciiMode
boolean
Default: false

Display results using ASCII characters

hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

languageCode
string

Display results in this language

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

sort
string

How to sort countries. Format: ±SORT_FIELD where SORT_FIELD = code | name

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Get country details

Get country details such as number of regions.

Authorizations:
UserSecurity
path Parameters
countryId
required
string

An ISO-3166 country code or WikiData id

query Parameters
asciiMode
boolean
Default: false

Display results using ASCII characters

languageCode
string

Display results in this language

Responses

Response samples

Content type
application/json
{}

Find country places

Get the country's places. The country is omitted in the response.

Authorizations:
UserSecurity
path Parameters
countryId
required
string

An ISO-3166 country code or WikiData id

query Parameters
minPopulation
integer <int32>

Only places having at least this population

maxPopulation
integer <int32>

Only places having no more than this population

namePrefix
string

Only entities whose names start with this prefix. If languageCode is set, the prefix will be matched on the name as it appears in that language.

namePrefixDefaultLangResults
boolean
Default: true

When name-prefix matching, whether or not to match on names in the default language if a non-default languageCode is set.

timeZoneIds
string

Only places in these time-zones (comma-delimited)

types
string

Only places for these types (comma-delimited): ADM2 | CITY | ISLAND

asciiMode
boolean
Default: false

Display results using ASCII characters

hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

languageCode
string

Display results in this language

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

sort
string

How to sort place results. 'Format: ±SORT_FIELD,±SORT_FIELD' where SORT_FIELD = elevation | name | population

includeDeleted
string
Default: "NONE"

Whether to include any divisions marked deleted: ALL | SINCE_YESTERDAY | SINCE_LAST_WEEK | NONE

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Find country regions

Get the country's regions. These could be states, provinces, districts, or otherwise major political divisions.

Authorizations:
UserSecurity
path Parameters
countryId
required
string

An ISO-3166 country code or WikiData id

query Parameters
namePrefix
string

Only entities whose names start with this prefix. If languageCode is set, the prefix will be matched on the name as it appears in that language.

namePrefixDefaultLangResults
boolean
Default: true

When name-prefix matching, whether or not to match on names in the default language if a non-default languageCode is set.

asciiMode
boolean
Default: false

Display results using ASCII characters

hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

languageCode
string

Display results in this language

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

sort
string

How to sort regions. Format: ±SORT_FIELD where SORT_FIELD = fipsCode | isoCode | name

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Get region details

Get country region details such as number of cities.

Authorizations:
UserSecurity
path Parameters
countryId
required
string

An ISO-3166 country code or WikiData id

regionCode
required
string

An ISO-3166 or FIPS region code

query Parameters
asciiMode
boolean
Default: false

Display results using ASCII characters

languageCode
string

Display results in this language

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ]
}

Find country region administrative divisions

Get country region administrative divisions. The country and region info is omitted in the response.

Authorizations:
UserSecurity
path Parameters
countryId
required
string

An ISO-3166 country code or WikiData id

regionCode
required
string

An ISO-3166 or FIPS region code

query Parameters
minPopulation
integer <int32>

Only places having at least this population

maxPopulation
integer <int32>

Only places having no more than this population

namePrefix
string

Only entities whose names start with this prefix. If languageCode is set, the prefix will be matched on the name as it appears in that language.

namePrefixDefaultLangResults
boolean
Default: true

When name-prefix matching, whether or not to match on names in the default language if a non-default languageCode is set.

timeZoneIds
string

Only places in these time-zones (comma-delimited)

asciiMode
boolean
Default: false

Display results using ASCII characters

hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

languageCode
string

Display results in this language

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

sort
string

How to sort place results. 'Format: ±SORT_FIELD,±SORT_FIELD' where SORT_FIELD = elevation | name | population

includeDeleted
string
Default: "NONE"

Whether to include any divisions marked deleted: ALL | SINCE_YESTERDAY | SINCE_LAST_WEEK | NONE

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Find country region cities

Get country region cities. The country and region info is omitted in the response.

Authorizations:
UserSecurity
path Parameters
countryId
required
string

An ISO-3166 country code or WikiData id

regionCode
required
string

An ISO-3166 or FIPS region code

query Parameters
minPopulation
integer <int32>

Only places having at least this population

maxPopulation
integer <int32>

Only places having no more than this population

namePrefix
string

Only entities whose names start with this prefix. If languageCode is set, the prefix will be matched on the name as it appears in that language.

namePrefixDefaultLangResults
boolean
Default: true

When name-prefix matching, whether or not to match on names in the default language if a non-default languageCode is set.

timeZoneIds
string

Only places in these time-zones (comma-delimited)

types
string

Only cities for these types (comma-delimited): ADM2 | CITY

asciiMode
boolean
Default: false

Display results using ASCII characters

hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

languageCode
string

Display results in this language

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

sort
string

How to sort place results. 'Format: ±SORT_FIELD,±SORT_FIELD' where SORT_FIELD = elevation | name | population

includeDeleted
string
Default: "NONE"

Whether to include any divisions marked deleted: ALL | SINCE_YESTERDAY | SINCE_LAST_WEEK | NONE

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Find country region places

Get country region places. The country and region info is omitted in the response.

Authorizations:
UserSecurity
path Parameters
countryId
required
string

An ISO-3166 country code or WikiData id

regionCode
required
string

An ISO-3166 or FIPS region code

query Parameters
minPopulation
integer <int32>

Only places having at least this population

maxPopulation
integer <int32>

Only places having no more than this population

namePrefix
string

Only entities whose names start with this prefix. If languageCode is set, the prefix will be matched on the name as it appears in that language.

namePrefixDefaultLangResults
boolean
Default: true

When name-prefix matching, whether or not to match on names in the default language if a non-default languageCode is set.

timeZoneIds
string

Only places in these time-zones (comma-delimited)

types
string

Only places for these types (comma-delimited): ADM2 | CITY | ISLAND

asciiMode
boolean
Default: false

Display results using ASCII characters

hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

languageCode
string

Display results in this language

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

sort
string

How to sort place results. 'Format: ±SORT_FIELD,±SORT_FIELD' where SORT_FIELD = elevation | name | population

includeDeleted
string
Default: "NONE"

Whether to include any divisions marked deleted: ALL | SINCE_YESTERDAY | SINCE_LAST_WEEK | NONE

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Find cities near location

Find cities near the given location, filtering by optional criteria. If no criteria are set, you will get back all cities within the default radius.

Authorizations:
UserSecurity
path Parameters
locationId
required
string

A latitude/longitude in ISO-6709 format: ±DD.DDDD±DDD.DDDD

query Parameters
radius
integer <int32>

The location radius within which to find places

distanceUnit
string
Default: "MI"

The unit of distance: MI | KM

countryIds
string

Only places in these countries (comma-delimited country codes or WikiData ids)

excludedCountryIds
string

Only places NOT in these countries (comma-delimited country codes or WikiData ids)

minPopulation
integer <int32>

Only places having at least this population

maxPopulation
integer <int32>

Only places having no more than this population

namePrefix
string

Only entities whose names start with this prefix. If languageCode is set, the prefix will be matched on the name as it appears in that language.

namePrefixDefaultLangResults
boolean
Default: true

When name-prefix matching, whether or not to match on names in the default language if a non-default languageCode is set.

timeZoneIds
string

Only places in these time-zones (comma-delimited)

types
string

Only cities for these types (comma-delimited): ADM2 | CITY

asciiMode
boolean
Default: false

Display results using ASCII characters

hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

languageCode
string

Display results in this language

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

sort
string

How to sort places. Format: ±SORT_FIELD,±SORT_FIELD where SORT_FIELD = countryCode | elevation | name | population

includeDeleted
string
Default: "NONE"

Whether to include any divisions marked deleted: ALL | SINCE_YESTERDAY | SINCE_LAST_WEEK | NONE

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Find admin divisions near location

Find administrative divisions near the given location, filtering by optional criteria. If no criteria are set, you will get back all divisions within the default radius.

Authorizations:
UserSecurity
path Parameters
locationId
required
string

A latitude/longitude in ISO-6709 format: ±DD.DDDD±DDD.DDDD

query Parameters
radius
integer <int32>

The location radius within which to find places

distanceUnit
string
Default: "MI"

The unit of distance: MI | KM

countryIds
string

Only places in these countries (comma-delimited country codes or WikiData ids)

excludedCountryIds
string

Only places NOT in these countries (comma-delimited country codes or WikiData ids)

minPopulation
integer <int32>

Only places having at least this population

maxPopulation
integer <int32>

Only places having no more than this population

namePrefix
string

Only entities whose names start with this prefix. If languageCode is set, the prefix will be matched on the name as it appears in that language.

namePrefixDefaultLangResults
boolean
Default: true

When name-prefix matching, whether or not to match on names in the default language if a non-default languageCode is set.

timeZoneIds
string

Only places in these time-zones (comma-delimited)

asciiMode
boolean
Default: false

Display results using ASCII characters

hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

languageCode
string

Display results in this language

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

sort
string

How to sort places. Format: ±SORT_FIELD,±SORT_FIELD where SORT_FIELD = countryCode | elevation | name | population

includeDeleted
string
Default: "NONE"

Whether to include any divisions marked deleted: ALL | SINCE_YESTERDAY | SINCE_LAST_WEEK | NONE

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Find places near location

Find places near the given location, filtering by optional criteria. If no criteria are set, you will get back all places within the default radius.

Authorizations:
UserSecurity
path Parameters
locationId
required
string

A latitude/longitude in ISO-6709 format: ±DD.DDDD±DDD.DDDD

query Parameters
radius
integer <int32>

The location radius within which to find places

distanceUnit
string
Default: "MI"

The unit of distance: MI | KM

countryIds
string

Only places in these countries (comma-delimited country codes or WikiData ids)

excludedCountryIds
string

Only places NOT in these countries (comma-delimited country codes or WikiData ids)

minPopulation
integer <int32>

Only places having at least this population

maxPopulation
integer <int32>

Only places having no more than this population

namePrefix
string

Only entities whose names start with this prefix. If languageCode is set, the prefix will be matched on the name as it appears in that language.

namePrefixDefaultLangResults
boolean
Default: true

When name-prefix matching, whether or not to match on names in the default language if a non-default languageCode is set.

timeZoneIds
string

Only places in these time-zones (comma-delimited)

types
string

Only places for these types (comma-delimited): ADM2 | CITY | ISLAND

asciiMode
boolean
Default: false

Display results using ASCII characters

hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

languageCode
string

Display results in this language

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

sort
string

How to sort places. Format: ±SORT_FIELD,±SORT_FIELD where SORT_FIELD = countryCode | elevation | name | population

includeDeleted
string
Default: "NONE"

Whether to include any divisions marked deleted: ALL | SINCE_YESTERDAY | SINCE_LAST_WEEK | NONE

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Find places

Find places, filtering by optional criteria. If no criteria are set, you will get back all known places.

Authorizations:
UserSecurity
query Parameters
location
string

Only places near this location. Latitude/longitude in ISO-6709 format: ±DD.DDDD±DDD.DDDD

radius
integer <int32>

The location radius within which to find places

distanceUnit
string
Default: "MI"

The unit of distance: MI | KM

countryIds
string

Only places in these countries (comma-delimited country codes or WikiData ids)

excludedCountryIds
string

Only places NOT in these countries (comma-delimited country codes or WikiData ids)

minPopulation
integer <int32>

Only places having at least this population

maxPopulation
integer <int32>

Only places having no more than this population

namePrefix
string

Only entities whose names start with this prefix. If languageCode is set, the prefix will be matched on the name as it appears in that language.

namePrefixDefaultLangResults
boolean
Default: true

When name-prefix matching, whether or not to match on names in the default language if a non-default languageCode is set.

timeZoneIds
string

Only places in these time-zones (comma-delimited)

types
string

Only places for these types (comma-delimited): ADM2 | CITY | ISLAND

asciiMode
boolean
Default: false

Display results using ASCII characters

hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

languageCode
string

Display results in this language

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

sort
string

How to sort places. Format: ±SORT_FIELD,±SORT_FIELD where SORT_FIELD = countryCode | elevation | name | population

includeDeleted
string
Default: "NONE"

Whether to include any divisions marked deleted: ALL | SINCE_YESTERDAY | SINCE_LAST_WEEK | NONE

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Find places near place

Find places near the given place, filtering by optional criteria. If no criteria are set, you will get back all places within the default radius.

Authorizations:
UserSecurity
path Parameters
placeId
required
string

A place id (either native 'id' or 'wikiDataId')

query Parameters
radius
integer <int32>

The location radius within which to find places

distanceUnit
string
Default: "MI"

The unit of distance: MI | KM

countryIds
string

Only places in these countries (comma-delimited country codes or WikiData ids)

excludedCountryIds
string

Only places NOT in these countries (comma-delimited country codes or WikiData ids)

minPopulation
integer <int32>

Only places having at least this population

maxPopulation
integer <int32>

Only places having no more than this population

namePrefix
string

Only entities whose names start with this prefix. If languageCode is set, the prefix will be matched on the name as it appears in that language.

namePrefixDefaultLangResults
boolean
Default: true

When name-prefix matching, whether or not to match on names in the default language if a non-default languageCode is set.

timeZoneIds
string

Only places in these time-zones (comma-delimited)

types
string

Only places for these types (comma-delimited): ADM2 | CITY | ISLAND

asciiMode
boolean
Default: false

Display results using ASCII characters

hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

languageCode
string

Display results in this language

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

sort
string

How to sort places. Format: ±SORT_FIELD,±SORT_FIELD where SORT_FIELD = countryCode | elevation | name | population

includeDeleted
string
Default: "NONE"

Whether to include any divisions marked deleted: ALL | SINCE_YESTERDAY | SINCE_LAST_WEEK | NONE

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Get place details

Get place details such as location coordinates, population, and elevation above sea-level (if available).

Authorizations:
UserSecurity
path Parameters
placeId
required
string

A place id (either native 'id' or 'wikiDataId')

query Parameters
asciiMode
boolean
Default: false

Display results using ASCII characters

languageCode
string

Display results in this language

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ]
}

Get place distance

Get distance from the given place

Authorizations:
UserSecurity
path Parameters
placeId
required
string

A place id (either native 'id' or 'wikiDataId')

query Parameters
toPlaceId
required
string

Distance to this place

distanceUnit
string
Default: "MI"

The unit of distance: MI | KM

Responses

Response samples

Content type
application/json
{
  • "data": 0.8008281904610115,
  • "errors": [
    ]
}

Get place date-time

Get place date-time

Authorizations:
UserSecurity
path Parameters
placeId
required
string

A place id (either native 'id' or 'wikiDataId')

Responses

Response samples

Content type
application/json
{
  • "data": "2000-01-23T04:56:07.000+00:00",
  • "errors": [
    ]
}

Get place containing region

Get the details for the containing populated place (e.g., its county or other administrative division), including location coordinates, population, and elevation above sea-level (if available).

Authorizations:
UserSecurity
path Parameters
placeId
required
string

A place id (either native 'id' or 'wikiDataId')

query Parameters
asciiMode
boolean
Default: false

Display results using ASCII characters

languageCode
string

Display results in this language

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "errors": [
    ]
}

Get place time

Get place time

Authorizations:
UserSecurity
path Parameters
placeId
required
string

A place id (either native 'id' or 'wikiDataId')

Responses

Response samples

Content type
application/json
{
  • "data": "data",
  • "errors": [
    ]
}

Locale

Locale Endpoints

Find currencies

Find currencies, filtering by optional criteria. If no criteria are set, you will get back all known currencies.

Authorizations:
UserSecurity
query Parameters
countryId
required
string

Currencies for this country id

hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Get languages

Get all supported languages

Authorizations:
UserSecurity
query Parameters
hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Get locales

Get all known locales

Authorizations:
UserSecurity
query Parameters
hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Get time-zones

Get all known time-zones

Authorizations:
UserSecurity
query Parameters
hateoasMode
boolean
Default: true

Include HATEOAS-style links in results

limit
integer <int32>
Default: 10

The maximum number of results to retrieve

offset
integer <int32>
Default: 0

The zero-ary offset index into the results

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ],
  • "links": [
    ],
  • "errors": [
    ]
}

Get time-zone

Get time-zone

Authorizations:
UserSecurity
path Parameters
zoneId
required
string

A time-zone id

Responses

Response samples

Content type
application/json
{
  • "rawUtcOffsetHours": 0,
  • "name": "name",
  • "id": "id",
  • "errors": [
    ]
}

Get time-zone date-time

Get time-zone date-time

Authorizations:
UserSecurity
path Parameters
zoneId
required
string

A time-zone id

Responses

Response samples

Content type
application/json
{
  • "data": "2000-01-23T04:56:07.000+00:00",
  • "errors": [
    ]
}

Get time-zone time

Get time-zone time

Authorizations:
UserSecurity
path Parameters
zoneId
required
string

A time-zone id

Responses

Response samples

Content type
application/json
{
  • "data": "data",
  • "errors": [
    ]
}