BigDataCloud Logo
How to convert getCurrentPosition results to city name for free using ReverseGeocoding API?
FreeReverse Geocoding

How to convert getCurrentPosition results to city name for free using ReverseGeocoding API?

BigDataCloud January 15, 2020

Share

These days it is quite common to see websites asking permission to access user locations. There are multiple use-cases of using location data to personalise your web content and deliver targeted messaging. 

This feature can be enabled in any website by using HTML 5 Geolocation API and is widely supported by all current web browsers including Chrome, Safari, Firefox, IE and Opera.

Know your location browser popup

The API can be used by calling navigator.geolocation.getCurrentPosition() function in any frontend javascript code. The following is an example implementation of this feature. 

var x = document.getElementById("demo");
function getLocation() {
  if (navigator.geolocation) {
    navigator.geolocation.getCurrentPosition(showPosition);
  } else {
    x.innerHTML = "Geolocation is not supported by this browser.";
  }
}

function showPosition(position) {
  x.innerHTML = "Latitude: " + position.coords.latitude +
  "<br>Longitude: " + position.coords.longitude;
}

The main function which triggers the browser to prompt a user to share his/her location is:

navigator.geolocation.getCurrentPosition(showPosition);

This will return a simple latitude and longitude coordinates of the user. In most instances, this coordinate is not particularly useful until it is converted into detailed locality information.

This is where a Reverse Geocoding API comes into play. There are various APIs available in the market for converting your geo-coordinate into readable location information. You can read more about it in our previous blog post about BigDataCloud’s Reverse Geocoding API.

BigDataCloud's Reverse Geocoding API is the first to deliver administrative/non-administrative boundaries-based results and as such, it is the perfect choice when you need to resolve a user's practical area such as their city, state or country rather than their street address.

The API provides:

  •     Detailed locality information of a user 
  •     Postal code level accuracy for the U.S, Great Britain, and Australia. 
  •     Exceptionally fast response time (sub-millisecond) 
  •     Supports 147 common world languages. 
  •     Unlimited FREE Client-Side Reverse Geocoding to City API 
  •     Affordable Server-Side Reverse Geocoding API 

For any developers who need real-time and accurate user location, BigDataCloud is the perfect solution.

Using BigDataCloud’s Free Reverse Geocoding API

BigDataCloud has 2 types of Reverse Geocoding API :

  1.     FREE Client-Side Reverse Geocoding to City API
  2.     Reverse Geocoding to City API (Free up to 50,000 queries per month)

The Client-side API is free to use with unlimited requests. A BigDataCloud account is not required to use this API. You can call the API within your javascript and convert the coordinate into locality information without an API key.

FREE Client-Side Reverse Geocoding to City API

The API is straight forward. Simply pass the latitude and longitude retrieved by the getCurrentPosition function and you will receive a JSON output contained detailed locality information.

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

The output of the API in JSON format.

{
    "latitude": 37.42158889770508,
    "longitude": -122.08370208740234,
    "localityLanguageRequested": "en",
    "continent": "North America",
    "continentCode": "NA",
    "countryName": "United States of America",
    "countryCode": "US",
    "principalSubdivision": "California",
    "locality": "Mountain View",
    "postcode": "94043",
    "localityInfo": {
        "administrative": [
            {
                "order": 1,
                "adminLevel": 2,
                "name": "United States of America",
                "description": "country in North America",
                "isoName": "United States of America (the)",
                "isoCode": "US",
                "wikidataId": "Q30"
            },
            {
                "order": 2,
                "adminLevel": 4,
                "name": "California",
                "description": "state of the United States of America",
                "isoName": "California",
                "isoCode": "US-CA",
                "wikidataId": "Q99"
            },
            {
                "order": 4,
                "adminLevel": 6,
                "name": "Santa Clara County",
                "description": "county in California, United States",
                "wikidataId": "Q110739"
            },
            {
                "order": 5,
                "adminLevel": 8,
                "name": "Mountain View",
                "description": "city in Santa Clara County, California, United States",
                "wikidataId": "Q486860"
            }
        ],
        "informative": [
            {
                "order": 0,
                "name": "North America",
                "description": "continent on the Earth's northwestern quadrant",
                "isoCode": "NA",
                "wikidataId": "Q49"
            },
            {
                "order": 3,
                "name": "Pacific Coast Ranges",
                "description": "mountain ranges in North America",
                "wikidataId": "Q660304"
            },
            {
                "order": 6,
                "name": "94043",
                "description": "postal code"
            },
            {
                "order": 7,
                "name": "Googleplex",
                "description": "building complex in California, United States",
                "wikidataId": "Q694178"
            }
        ]
    }
}

Code Pen Example

 

 

Please click here to test the demo on CodePen.

Javascript Library

BigDataCloud also offers a purpose-built  Javascript client library for using the Free Reverse Geocoding API. This client works without any dependencies and has no API key or account requirements. Simply load it up and start Reverse Geocoding your customer's locations.

GitHub page for Reverse Geocoding API

Best practises of using the FREE Client-side API

The Reverse Geocoding API is free to use for client-side implementations only. If you wish to implement the API in a server-side application or scenario then you will need to use the server-side API version which comes with a FREE allowance of 50,000 requests per month.

The client-side API is restricted to client-side implementations only and if you are found abusing the API then your account will be banned. 

Client-side implementation means that the API should be called in real-time when the user provides their geo-coordinates via browsers, mobile apps or desktop apps. Any operations on stored geo-coordinate values from database, file or internal variables, which are not originating from the user’s action(client-side), will be considered a server-side implementation. 

The above example Javascript codes using getCurrentPosition() is the perfect use case of the FREE Client-side API. The request is made at the time of collecting the geo-coordinate on behalf of the visiting user, with the result being used for any situation.

A server-side example would be to capture the latitude and longitude from the browser and to submit this coordinate to the server for processing. A regular use-case for this scenario is to geo-tag content submissions such as photos or videos which can then be further identified and processed using a Reverse Geocoding API, often in batch execution. In this instance, the server would be performing the API request at a separate time and from a separate location. Requests of this type are not permitted on the Free Client-side API and must be made using the Server-side API.

Share