FREE Client Side Reverse Geocoding to City API

Introduction

This free Client-side Reverse Geocoding API is the fastest and most straightforward way to convert your user’s real-time geo coordinates (latitude/longitude) into detailed locality information, on the client side.

You can easily implement it with a browser's HTML5 geolocation API or a mobile phone's location services. If the user doesn't share their location, the API will automatically utilise BigDataCloud's superior IP geolocation technology to offer the most accurate location data based on the user's IP address.

Please refer to our blog post titled "Free client-side reverse geocoding API with IP geolocation fallback" for a more comprehensive explanation of this unique fallback mechanism.

Key Benefits of the BigDataCloud’s Free Client-Side Reverse Geocoding API

Free and Unique features

  • Free forever! No contract, no hidden fees, and no account required.
  • Automatically reverts to the world’s most precise, next-generation, patented IP Geolocation technology when a client’s geocoordinates are unavailable.
  • Both commercial and non-commercial uses are permitted with no rate restrictions – we’re happy to accept literally any number of API queries at any pace as long as conditions of our Fair Use Policy are met (see below).

Superior Speed and Reliability

  • Unprecedentedly fast response time (sub-millisecond)
  • Enterprise-grade redundant infrastructure. Operated from ten geographically diverse data centres across the globe
  • Better than 99.999% availability
  • Predictable performance as no caching is used

Accurate Location Data

  • Delivers administrative/non-administrative boundaries-based results
  • Provides detailed locality information of a user in 148 common world languages
  • Full postal code level geographical accuracy for the US, Great Britain, and Australia (partial for other countries)
  • Full global coverage, including seas and oceans
  • Geocoder data is updated weekly, and IP Geolocation is daily.

Privacy-Friendly and Responsive Support

  • Friendly with GDPR and GDPR-like privacy laws
  • Responsive customer support, even for entirely free APIs

Fair Use Policy for FREE Client-Side Reverse Geocoding API implementation

  1. You are allowed to make free and unlimited API calls from a client's web browser using their current coordinates obtained by the browser’s getCurrentPosition() method when consent is given or without the coordinates if denied.
  2. You are allowed to make unlimited free API calls from client mobile devices such as iOS, Android or IoT devices using their current coordinates when the consent is given or without the coordinates if denied.
  3. Please contact us if you are unsure whether your implementation meets this Fair Use Policy.

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.

IMPORTANT! Any user detected abusing the service by implementing it on a server-side or a client-side along with coordinates obtained elsewhere 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.

Learn how to avoid getting your IP address banned.

Get Started

This API is part of the FREE API Package and is available in free and paid plans. Please visit the FREE API Package package page for limits and pricing information.

Endpoint

IPv4 only API Endpoint

Use this endpoint to force API calls routed over the IPv4 network only

GET
https://api.bigdatacloud.net/data/reverse-geocode-client
Impotant! This API does not have a dual-stack API endpoint and is currently not supported over an IPv6 network

Request

Parameter
latitude
Type
string
Required
Yes
Description
Latitude value as per WGS 84 reference system (GPS system). Expected values are in [-90, 90] range
Parameter
longitude
Type
string
Required
Yes
Description
Longitude value as per WGS 84 reference system (GPS system). Expected values are in [-180, 180] range
Parameter
localityLanguage
Type
string
Required
Optional, default value: en
Description
Preferred language for locality names in ISO 639-1 format, such as 'en' for English, 'es' for Spanish etc. If the requested language is unavailable for a requested location, it will default to English. If no English variant is available, will provide the native, local names. Use 'default' as the requested value to automatically adjust the language to the first administrative language in the Country.

Responses

200
Success

Sample Query

GET
https://api.bigdatacloud.net/data/reverse-geocode-client?latitude=37.42159&longitude=-122.0837&localityLanguage=en

Schema

application/json
latitudenumber
Requested Latitude
lookupSourcestring
Indicates whether the results are based on reverse geocoding or IP Geolocation
longitudenumber
Requested Longitude
localityLanguageRequestedstring
localityLanguage input parameter received
continentstring
Localised Continent name in the requested language, if available
continentCodestring
Continent code
countryNamestring
Localised Country name in the requested language, if available
countryCodestring
Country code as defined by ISO 3166-1 standard
principalSubdivisionstring
Localised principal subdivision name in the requested language, if available
principalSubdivisionCodestring
Principal subdivision code as defined by ISO 3166-2 standard
citystring
The most significant populated place this location belongs. It will likely be the City name in the language requested. If unavailable, use the locality name field as a failover
localitystring
Represents the smallest geographic area recognised to which the target belongs. The language, if available, is as defined by 'localityLanguage' request parameter
postcodestring
Postcode, if available
plusCodestring
Open Location Code
fips
FIPS code object, omitted if unavailable. FIPS (Federal Information Processing Standards) Codes are codes used by the Census Bureau to uniquely identify places in the US. Visit FIPS FAQ page for more information.
statestring
State-level FIPS codes have two digits
countystring
A three digits County-level FIPS code.
countySubdivisionstring
FIPS five digits County Subdivision Code
placestring
FIPS five digits place code, omitted if unavailable
csdCodestring
CSD (Census Subdivision) code, omitted if unavailable. Canadian Geographic Codes. Visit CSD FAQ page for more information.
localityInfo
localityInfo object
administrativearray
Administrative authorities as ordered by area (most significant first). Omitted if no administrative boundaries are available
namestring
Localised name of the place in the requested language, if available. The language is as defined by the 'localityLanguage' request parameter
descriptionstring
Localised description of the place in the requested language, if available. The language is as defined by the 'localityLanguage' request parameter
isoNamestring
ISO 3166-2 standard name, if available
orderinteger
Order value consistent across all entities in the Locality Info parent object. Ordered by geographic area (most significant first)
adminLevelinteger
An administrative level as defined by OpenStreetMaps project
isoCodestring
ISO 3166-2 standard code, if available
wikidataIdstring
Wikidata item identifier, if available
geonameIdinteger
Unique identifier given by GeoNames.org, if available
chinaAdminCodestring
China Administrative division code. Only available for locations based in China and omitted for others
informativearray
Non-administrative boundaries as ordered by area (most significant first). Omitted if unavailable
namestring
Localised name of the place in the requested language, if available. The language is as defined by the 'localityLanguage' request parameter
descriptionstring
Localised description of the place in the requested language, if available. The language is as defined by the 'localityLanguage' request parameter
isoNamestring
ISO 3166-2 standard name, if available
orderinteger
Order value consistent across all entities in the Locality Info parent object. Ordered by geographic area (most significant first)
adminLevelinteger
An administrative level as defined by OpenStreetMaps project
isoCodestring
ISO 3166-2 standard code, if available
wikidataIdstring
Wikidata item identifier, if available
geonameIdinteger
Unique identifier given by GeoNames.org, if available
chinaAdminCodestring
China Administrative division code. Only available for locations based in China and omitted for others

Sample Response

JSON View
400
Bad request

Sample Response

JSON View
401
Invalid coordinates

Sample Response

JSON View
402
This endpoint does not support server-side operations

Sample Response

JSON View
500
An error has occurred and did not complete your request. Please try again

Sample Response

JSON View
Was this page helpful?