Geo DB API API Reference

This developer-centric REST API focuses on getting global city and region data. Easily obtain country, region, and city data for use in your apps!

  • Filter cities by name prefix, country, location, and even minimum population.
  • Get all country regions.
  • Get all cities in a given region.
  • Developer-friendly RESTful API adheres to industry best-practices, including HATEOS-style links to facilitate paging results.
  • Backed by Amazon AWS load-balanced infrastructure for resiliency and performance!
  • Data is periodically refreshed from GeoNames.org.

Notes:

  • All endpoints implicitly support JSONP-style invocation via an optional callback param.
  • Since the database is periodically updated, this may very rarely result in certain cities being marked deleted (e.g., duplicates removed). By default, endpoints returning city data will exclude cities marked deleted. However, in the unlikely event that this occurs while your app is paging through a set of affected results - and you care about the paged results suddenly changing underneath - specify includeDeleted=SINCE_YESTERDAY (or SINCE_LAST_WEEK if you're really paranoid!).

Useful Links:

API Endpoint
https://wft-geo-db.p.mashape.com/
Response Content-Types: application/json
Schemes: https
Version: 1.0.0

Authentication

UserSecurity

name
X-Mashape-Key
in
header

Geo

Geo Endpoints

Geo

Get cities

GET /v1/geo/cities

Get cities, filtering by optional criteria. If no criteria are set, you will get back all known cities with a population of at least 1000. (Currently over 115,000.) If countryCode is specified, the country info will be omitted in the response.

namePrefix

Only cities whose names start with this prefix

type
string
in
query
countryCode

Only cities in this country

type
string
in
query
minPopulation

Only cities having at least this population

type
integer (int32)
in
query
nearLocation

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

type
string
in
query
nearLocationRadius

The location radius within which to find cities

type
integer (int32)
in
query
nearLocationRadiusUnit

The location radius unit of distance: MI | KM

type
string MI
in
query
includeDeleted

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

type
string NONE
in
query
limit

The maximum number of results to retrieve

type
integer (int32) 10
in
query
offset

The zero-ary offset index into the results

type
integer (int32)
in
query

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "data": [
    {
      "city": "string",
      "country": "string",
      "countryCode": "string",
      "id": "integer (int32)",
      "region": "string",
      "regionCode": "string"
    }
  ],
  "errors": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "links": [
    {
      "href": "string",
      "rel": "string"
    }
  ],
  "metadata": {
    "currentOffset": "integer (int64)",
    "totalCount": "integer (int64)"
  }
}
Geo

Get city details

GET /v1/geo/cities/{cityId}

Get the details for a specific city, including location coordinates, population, and elevation above sea-level (if available).

cityId

The city id

type
integer (int32)
in
path
200 OK

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "data": {
    "city": "string",
    "country": "string",
    "countryCode": "string",
    "deleted": "boolean",
    "elevationMeters": "integer (int32)",
    "id": "integer (int32)",
    "location": {
      "latitude": "number (double)",
      "longitude": "number (double)"
    },
    "population": "integer (int32)",
    "region": "string",
    "regionCode": "string"
  },
  "errors": [
    {
      "code": "string",
      "message": "string"
    }
  ]
}
Geo

Get countries

GET /v1/geo/countries

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

currencyCode

Only countries supporting this currency

type
string
in
query
limit

The maximum number of results to retrieve

type
integer (int32) 10
in
query
offset

The zero-ary offset index into the results

type
integer (int32)
in
query

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "data": [
    {
      "code": "string",
      "currencyCode": "string",
      "name": "string"
    }
  ],
  "errors": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "links": [
    {
      "href": "string",
      "rel": "string"
    }
  ],
  "metadata": {
    "currentOffset": "integer (int64)",
    "totalCount": "integer (int64)"
  }
}
Geo

Get country details

GET /v1/geo/countries/{countryCode}

Get the details for a specific country, including number of regions.

countryCode

An ISO-3166 country code

type
string
in
path

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "data": {
    "code": "string",
    "currencyCode": "string",
    "name": "string",
    "numRegions": "integer (int32)"
  },
  "errors": [
    {
      "code": "string",
      "message": "string"
    }
  ]
}
Geo

Get country regions

GET /v1/geo/countries/{countryCode}/regions

Get all regions in a specific country. These could be states, provinces, districts, or otherwise major political divisions.

countryCode

An ISO-3166 country code

type
string
in
path
limit

The maximum number of results to retrieve

type
integer (int32) 10
in
query
offset

The zero-ary offset index into the results

type
integer (int32)
in
query

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "data": [
    {
      "countryCode": "string",
      "fipsCode": "string",
      "hascCode": "string",
      "isoCode": "string",
      "name": "string"
    }
  ],
  "errors": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "links": [
    {
      "href": "string",
      "rel": "string"
    }
  ],
  "metadata": {
    "currentOffset": "integer (int64)",
    "totalCount": "integer (int64)"
  }
}
Geo

Get region details

GET /v1/geo/countries/{countryCode}/regions/{regionCode}

Get the details of a specific country region, including number of cities.

countryCode

An ISO-3166 country code

type
string
in
path
regionCode

An HASC, ISO-3166, or FIPS region code

type
string
in
path

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "data": {
    "capital": "string",
    "countryCode": "string",
    "fipsCode": "string",
    "hascCode": "string",
    "isoCode": "string",
    "name": "string",
    "numCities": "integer (int32)"
  },
  "errors": [
    {
      "code": "string",
      "message": "string"
    }
  ]
}
Geo

Get country region cities

GET /v1/geo/countries/{countryCode}/regions/{regionCode}/cities

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

countryCode

An ISO-3166 country code

type
string
in
path
regionCode

An HASC, ISO-3166, or FIPS region code

type
string
in
path
minPopulation

Only cities having at least this population

type
integer (int32)
in
query
includeDeleted

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

type
string NONE
in
query
limit

The maximum number of results to retrieve

type
integer (int32) 10
in
query
offset

The zero-ary offset index into the results

type
integer (int32)
in
query

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "data": [
    {
      "city": "string",
      "country": "string",
      "countryCode": "string",
      "id": "integer (int32)",
      "region": "string",
      "regionCode": "string"
    }
  ],
  "errors": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "links": [
    {
      "href": "string",
      "rel": "string"
    }
  ],
  "metadata": {
    "currentOffset": "integer (int64)",
    "totalCount": "integer (int64)"
  }
}

Locale

Locale Endpoints

Get currencies

GET /v1/locale/currencies

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

countryCode

Only currencies supported by this country

type
string
in
query
limit

The maximum number of results to retrieve

type
integer (int32) 10
in
query
offset

The zero-ary offset index into the results

type
integer (int32)
in
query

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "data": [
    {
      "code": "string",
      "countryCodes": [
        "string"
      ]
    }
  ],
  "errors": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "links": [
    {
      "href": "string",
      "rel": "string"
    }
  ],
  "metadata": {
    "currentOffset": "integer (int64)",
    "totalCount": "integer (int64)"
  }
}

Get locales

GET /v1/locale/locales

Get all known locales

limit

The maximum number of results to retrieve

type
integer (int32) 10
in
query
offset

The zero-ary offset index into the results

type
integer (int32)
in
query

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "data": [
    {
      "code": "string"
    }
  ],
  "errors": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "links": [
    {
      "href": "string",
      "rel": "string"
    }
  ],
  "metadata": {
    "currentOffset": "integer (int64)",
    "totalCount": "integer (int64)"
  }
}

Schema Definitions

CitiesResponse: object

data: object[]

A list of CitySummaries

errors: object[]

A list of WftErrors

links: object[]

A list of Links

metadata: Metadata
Example
{
  "data": [
    {
      "city": "string",
      "country": "string",
      "countryCode": "string",
      "id": "integer (int32)",
      "region": "string",
      "regionCode": "string"
    }
  ],
  "errors": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "links": [
    {
      "href": "string",
      "rel": "string"
    }
  ],
  "metadata": {
    "currentOffset": "integer (int64)",
    "totalCount": "integer (int64)"
  }
}

CityDetails: object

city: string
country: string
countryCode: string
deleted: boolean
elevationMeters: integer (int32)
id: integer (int32)
location: GeoLocation
population: integer (int32)
region: string
regionCode: string
Example
{
  "city": "string",
  "country": "string",
  "countryCode": "string",
  "deleted": "boolean",
  "elevationMeters": "integer (int32)",
  "id": "integer (int32)",
  "location": {
    "latitude": "number (double)",
    "longitude": "number (double)"
  },
  "population": "integer (int32)",
  "region": "string",
  "regionCode": "string"
}

CityResponse: object

data: CityDetails
errors: object[]

A list of WftErrors

Example
{
  "data": {
    "city": "string",
    "country": "string",
    "countryCode": "string",
    "deleted": "boolean",
    "elevationMeters": "integer (int32)",
    "id": "integer (int32)",
    "location": {
      "latitude": "number (double)",
      "longitude": "number (double)"
    },
    "population": "integer (int32)",
    "region": "string",
    "regionCode": "string"
  },
  "errors": [
    {
      "code": "string",
      "message": "string"
    }
  ]
}

CitySummary: object

city: string
country: string
countryCode: string
id: integer (int32)
region: string
regionCode: string
Example
{
  "city": "string",
  "country": "string",
  "countryCode": "string",
  "id": "integer (int32)",
  "region": "string",
  "regionCode": "string"
}

CountriesResponse: object

data: object[]

A list of CountrySummarys

errors: object[]

A list of WftErrors

links: object[]

A list of Links

metadata: Metadata
Example
{
  "data": [
    {
      "code": "string",
      "currencyCode": "string",
      "name": "string"
    }
  ],
  "errors": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "links": [
    {
      "href": "string",
      "rel": "string"
    }
  ],
  "metadata": {
    "currentOffset": "integer (int64)",
    "totalCount": "integer (int64)"
  }
}

CountrySummary: object

code: string
currencyCode: string

A ISO-4217 currency code

name: string
Example
{
  "code": "string",
  "currencyCode": "string",
  "name": "string"
}

CountryDetails: object

code: string
currencyCode: string

A ISO-4217 currency code

name: string
numRegions: integer (int32)
Example
{
  "code": "string",
  "currencyCode": "string",
  "name": "string",
  "numRegions": "integer (int32)"
}

CountryResponse: object

data: CountryDetails
errors: object[]

A list of WftErrors

Example
{
  "data": {
    "code": "string",
    "currencyCode": "string",
    "name": "string",
    "numRegions": "integer (int32)"
  },
  "errors": [
    {
      "code": "string",
      "message": "string"
    }
  ]
}

CurrenciesResponse: object

data: object[]

A list of CurrencyDescriptors

errors: object[]

A list of WftErrors

links: object[]

A list of Links

metadata: Metadata
Example
{
  "data": [
    {
      "code": "string",
      "countryCodes": [
        "string"
      ]
    }
  ],
  "errors": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "links": [
    {
      "href": "string",
      "rel": "string"
    }
  ],
  "metadata": {
    "currentOffset": "integer (int64)",
    "totalCount": "integer (int64)"
  }
}

CurrencyDescriptor: object

code: string

A ISO-4217 currency code

countryCodes: string[]

A list of ISO-3166 country codes

Example
{
  "code": "string",
  "countryCodes": [
    "string"
  ]
}

GeoLocation: object

latitude: number (double)
longitude: number (double)
Example
{
  "latitude": "number (double)",
  "longitude": "number (double)"
}

LocaleDescriptor: object

code: string
Example
{
  "code": "string"
}

LocalesResponse: object

data: object[]

A list of LocalDescriptors

errors: object[]

A list of WftErrors

links: object[]

A list of Links

metadata: Metadata
Example
{
  "data": [
    {
      "code": "string"
    }
  ],
  "errors": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "links": [
    {
      "href": "string",
      "rel": "string"
    }
  ],
  "metadata": {
    "currentOffset": "integer (int64)",
    "totalCount": "integer (int64)"
  }
}

Metadata: object

currentOffset: integer (int64)
totalCount: integer (int64)
Example
{
  "currentOffset": "integer (int64)",
  "totalCount": "integer (int64)"
}

RegionDetails: object

capital: string
countryCode: string

An ISO-3166 country code

fipsCode: string
hascCode: string
isoCode: string
name: string

The well-known internationally recognized name for this region

numCities: integer (int32)
Example
{
  "capital": "string",
  "countryCode": "string",
  "fipsCode": "string",
  "hascCode": "string",
  "isoCode": "string",
  "name": "string",
  "numCities": "integer (int32)"
}

RegionResponse: object

data: RegionDetails
errors: object[]

A list of WftErrors

Example
{
  "data": {
    "capital": "string",
    "countryCode": "string",
    "fipsCode": "string",
    "hascCode": "string",
    "isoCode": "string",
    "name": "string",
    "numCities": "integer (int32)"
  },
  "errors": [
    {
      "code": "string",
      "message": "string"
    }
  ]
}

RegionSummary: object

countryCode: string

An ISO-3166 country code

fipsCode: string
hascCode: string
isoCode: string
name: string
Example
{
  "countryCode": "string",
  "fipsCode": "string",
  "hascCode": "string",
  "isoCode": "string",
  "name": "string"
}

RegionsResponse: object

data: object[]

A list of RegionSummaries

errors: object[]

A list of WftErrors

links: object[]

A list of Links

metadata: Metadata
Example
{
  "data": [
    {
      "countryCode": "string",
      "fipsCode": "string",
      "hascCode": "string",
      "isoCode": "string",
      "name": "string"
    }
  ],
  "errors": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "links": [
    {
      "href": "string",
      "rel": "string"
    }
  ],
  "metadata": {
    "currentOffset": "integer (int64)",
    "totalCount": "integer (int64)"
  }
}

WftError: object

code: WftErrorCode
message: string
Example
{
  "code": "string",
  "message": "string"
}

WftErrorCode: string

string ACCESS_DENIED, ENTITY_NOT_FOUND, PARAM_INVALID, PARAMS_MUTUALLY_EXCLUSIVE