https://github.com/bigdatacloudapi/js-reverse-geocode-client

A frontend Javascript (JS) client for using the Free Reverse Geocoding API provided by BigDataCloud
https://github.com/bigdatacloudapi/js-reverse-geocode-client

geocoding geolocation javascript location reverse-geocoding

Last synced: 8 months ago
JSON representation

A frontend Javascript (JS) client for using the Free Reverse Geocoding API provided by BigDataCloud

• Host: GitHub
• URL: https://github.com/bigdatacloudapi/js-reverse-geocode-client
• Owner: bigdatacloudapi
• License: mit
• Created: 2019-10-07T03:16:28.000Z (about 6 years ago)
• Default Branch: master
• Last Pushed: 2023-12-18T20:43:47.000Z (almost 2 years ago)
• Last Synced: 2025-03-24T19:06:04.738Z (9 months ago)
• Topics: geocoding, geolocation, javascript, location, reverse-geocoding
• Language: JavaScript
• Homepage: https://www.bigdatacloud.com
• Size: 11.7 KB
• Stars: 20
• Watchers: 3
• Forks: 11
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# BigDataCloud Free Reverse Geocoding Javascript API Client

A frontend Javascript client for using the Free Reverse Geocoding API provided by [BigDataCloud](https://www.bigdatacloud.com)

This client works without any Javascript dependencies and has no API key or account requirement... Simply load it up and start Reverse Geocoding your customer's locations.

## Recent Changes

### 2021-05-06 

This client now supports graceful fallback when a user denies accessing their device location.

You can now get high quality location information on your users even when they do not provide their latitude/longitude.

This feature is only available in client-side use (see Usage limits below for more information)

[To find out how this works, view this blog post](https://www.bigdatacloud.com/blog/new-feature-update-free-client-side-reverse-geocoding-api-with-ip-geolocation-fallback).

## Documentation

Documentation specific to this Free API Client is detailed below.

For more information about the API, please visit [FREE Client-side Reverse Geocoding to City API](https://www.bigdatacloud.com/free-api/free-reverse-geocode-to-city-api).

## Authentication / Identification

There is no authentication or identification required to use this API or client.

You may use this API and client for Free without an account.

## Usage Limits

This client-side API is completely FREE for both commercial and non-commercial use, including unlimited usage with no throttling or limitations.

This particular API is for client-side use only. Any user found abusing this service by implementing it 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](https://www.bigdatacloud.com/reverse-geocoding) for pricing details.

## Manual Installation

1. Download the included javascript file and place it in a publically accessible location

2. Include the script tag `` before your code execution

3. Initiate the Reverse geocode API Client as per the below example

## CDN Installation

1. Include the CDN script tag `` before your code execution

2. Initiate the API Client and make the required calls as necessary

## Example usage

```javascript

    /* Initialise Reverse Geocode API Client */

    var reverseGeocoder=new BDCReverseGeocode();

    

    /* Get the current user's location information, based on the coordinates provided by their browser */

    /* Fetching coordinates requires the user to be accessing your page over HTTPS and to allow the location prompt. */

    reverseGeocoder.getClientLocation(function(result) {

        console.log(result);

    });

    /* Get the administrative location information using a set of known coordinates */

    reverseGeocoder.getClientLocation({

        latitude: -33.8688,

        longitude: 151.2093,

    },function(result) {

        console.log(result);

    });

    /* You can also set the locality language as needed */

    reverseGeocoder.localityLanguage='es';

    /* Request the current user's coordinates (requires HTTPS and acceptance of prompt) */

    reverseGeocoder.getClientCoordinates(function(result) {

        console.log(result);

    });

```

## Example output

```javascript

{

    "latitude": "-33.8688",

    "longitude": "151.2093",

    "localityLanguageRequested": "en",

    "countryName": "Australia",

    "principalSubdivision": "New South Wales",

    "locality": "Sydney",

    "localityInfo": {

        "administrative": [{

            "order": 1,

            "adminLevel": 2,

            "name": "Australia",

            "description": "country in Oceania",

            "isoName": "Australia",

            "isoCode": "AU",

            "wikidataId": "Q408"

        }, {

            "order": 2,

            "adminLevel": 4,

            "name": "New South Wales",

            "description": "state of Australia",

            "isoName": "New South Wales",

            "isoCode": "AU-NSW",

            "wikidataId": "Q3224"

        }, {

            "order": 3,

            "adminLevel": 7,

            "name": "Sydney",

            "description": "capital city of New South Wales, Australia",

            "wikidataId": "Q3130"

        }, {

            "order": 4,

            "adminLevel": 6,

            "name": "Council of the City of Sydney",

            "description": "municipality"

        }, {

            "order": 5,

            "adminLevel": 10,

            "name": "Sydney",

            "description": "central business district of Sydney, New South Wales, Australia",

            "wikidataId": "Q1852577"

        }]

    }

}

```