FREE Client Side Reverse Geocoding to City API

Introduction

The Free Client-side Reverse Geocoding to City API is a free version of Reverse Geocoding to City API which is strictly limited to the client-side implementations only.

A client-side application often requires making external API calls from a script language code, visible to a third party, like javascript for example. Utilising authenticated API requests on such can compromise security. Therefore, to protect our customers, we've decided to offer client-side implemented Reverse Geocoding with no API key required, hence totally for free.

IMPORTANT! The API is to be used ONLY for client-side implementation. Any user detected abusing the service by implementing it on server-side will be blacklisted from all of our free API Services. If you wish to utilise this Reverse Geocoding API in your backend applications, please visit our server-side variation of this API for details.

 

Fair Use Policy for Client-side implementation

There are two main categories of the client-side application allowed for this API:

  1. You're allowed to make free and unlimited API calls from the client's web browser
  2. You're allowed to make free and unlimited API calls from client's mobiles such as iOS, Android or IoT devices

 

Dos:

  • Use the API with HTML5's Geolocation API to identify the user's locality information. You can read about how you can do this in more detail in our blog here.
  • Use the API with the respective mobile platform's current location services to identify the user's locality info.

 

Don'ts:

  • Apply the API on stored geo-coordinates values from a file
  • Create a service which converts geo-coordinates to location information in bulk

 

For example, check out our free Where am I? iOS and Android app. The app demonstrates how you can implement the API for a mobile app to obtain real-time locality information for your users.

Example Response

The response is only available in JSON format. The below response should be expected for the following request:



Awaiting request submission...

API Pricing

Request Format

NEW! Payload compression is supported, simply add Accept-Encoding: gzip header.
Use the form below to try out this API.

Parameter Your Input Value Description
latitude

Latitude value as per WGS 84 reference system (GPS system). Expected values are in [-90, 90] range.

longitude

Longitude value as per WGS 84 reference system (GPS system). Expected values are in [-180, 180] range.

localityLanguage

Preferred language for locality names in ISO 639-1 format, such as 'en' for English, 'es' for Spanish etc. Please note: 147 common world languages are supported, full list here, but not all languages are available for every location. If requested language is not available for a requested location it will default to English, if no English is available, the native, local names will be provided



Response

Awaiting request submission...

Response Format


Field

Data type

Description

latitude

float

Requested Latitude

longitude

float

Requested Longitude

localityLanguageRequested

string

localityLanguage input parameter received

countryName

string

Country name. Omitted if not available

countryCode

string

Country code. Omitted if not available

principalSubdivision

string Principal subdivision. Omitted if not available

locality

string Locality name. Omitted if not available

postcode

string

Postcode. Omitted if not available

localityInfo

 <LocalityInfo> object

Detailed reverse geocoded locality information localised to the language as defined by ‘localityLanguage’ request parameter

Data Objects

Locality Info object

Field

Data type

Description

administrative

Aray of <LocalityProperty> objects

Administrative boundarires ordered by area (largest first). Omitted if no administrative boundaries are available

informative

Aray of <LocalityProperty> objects

Non-administrative boundarires ordered by area (largest first). Omitted if not available

Locality Property object

Field

Data type

Description

order

integer

Order value consistent across all entities in the Locality Info parent object. Ordered by area (largest first)

adminLevel

integer

An administrative level as defined by OpenStreetMaps project

name

string

Localised name. The language is as defined by ‘localityLanguage’ request parameter

description

string

Localised description. The language is as defined by ‘localityLanguage’ request parameter

isoName

string

ISO 3166-2 standard name, if available

isoCode

string

ISO 3166-2 standard code, if available

wikidataId

string

Wikidata item identifier, if available

 

Related APIs