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 August 18, 2025

Share

When you collect latitude/longitude coordinates in a web or mobile app, you often need to translate them into a human-readable place like a city or suburb. The browser’s navigator.geolocation.getCurrentPosition() gives you the coordinates — but not the place name. BigDataCloud’s free, client-side Reverse Geocode to City API solves this instantly, without an API key or account.

This guide shows you how to go from coordinates to a city/suburb name using our client-side only endpoint, explains fair use, and covers best practices, error handling and fallbacks.

Why use BigDataCloud’s client-side Reverse Geocoding?

Related reading: How accurate can IP geolocation get? · IP Geolocation Accuracy Report

Fair use — client-side only

The free endpoint is designed for real-time, client-side lookups initiated by a user’s device. There is no limitation on throughput as long as the Fair Use Policy is respected. Bulk, server-side or automated testing falls outside fair use.

💡 Developer tip: testing without violating fair use

During development, you may need to run many tests with different coordinates from the same location. This pattern clearly violates the Fair Use Policy and could result in your IP address being temporarily blocked.

  • Create a free BigDataCloud account and use the server-side Reverse Geocode to City API during development.
  • Both the client-side and server-side endpoints return the same JSON schema, so switching between them typically requires only changing the endpoint URL.
  • When your app goes live, switch back to the client-side free API in production. It supports unlimited legitimate throughput, provided requests are user-initiated and in line with fair use.

Implementation: step-by-step

1) Collect coordinates with getCurrentPosition()


function getCoords(options = { enableHighAccuracy: true, timeout: 10000, maximumAge: 0 }) {
  return new Promise((resolve, reject) => {
    if (!('geolocation' in navigator)) return reject(new Error('Geolocation is not supported'));
    navigator.geolocation.getCurrentPosition(
      (pos) => resolve({
        latitude: pos.coords.latitude,
        longitude: pos.coords.longitude,
        accuracy: pos.coords.accuracy
      }),
      (err) => reject(err),
      options
    );
  });
}

2) Reverse-geocode on the client

Call the free client-side endpoint on api.bigdatacloud.net. To protect privacy in this article, we’ll use a public landmark — the Sydney Opera House — instead of anyone’s current location.

  • Sample coordinates (public landmark): latitude=-33.8567844, longitude=151.2152967

async function reverseGeocode({ latitude, longitude, language = 'en' }) {
  const url = new URL('https://api.bigdatacloud.net/data/reverse-geocode-client');
  url.searchParams.set('latitude', latitude);
  url.searchParams.set('longitude', longitude);
  url.searchParams.set('localityLanguage', language);
  const res = await fetch(url.toString(), { method: 'GET' });
  if (!res.ok) throw new Error(`Reverse geocoding failed: ${res.status}`);
  return res.json();
}

// Example usage with the Sydney Opera House (public building)
(() => { const data = await reverseGeocode({ latitude: -33.8567844, longitude: 151.2152967, language: 'en'
}); const cityOrLocality = data.city || data.locality || ''; const region = data.principalSubdivision || ''; const country = data.countryName || ''; console.log(`Detected place: ${cityOrLocality}, ${region}, ${country}`);
})();

3) Example: full JSON response (representative)


{
  "latitude": -33.8567844,
  "longitude": 151.2152967,
  "localityLanguageRequested": "en",
  "continent": "Oceania",
  "continentCode": "OC",
  "countryName": "Australia",
  "countryCode": "AU",
  "principalSubdivision": "New South Wales",
  "principalSubdivisionCode": "AU-NSW",
  "city": "Sydney",
  "locality": "Sydney",
  "postcode": "2000",
  "location": {
    "lat": -33.8567844,
    "lon": 151.2152967
  },
  "plusCode": null,
  "localityInfo": ...
}

End-to-end example: collect and display location


async function detectPlaceName() {
  try {
    // For demo: public landmark (Sydney Opera House)
    const latitude = -33.8567844;
    const longitude = 151.2152967;
    const data = await reverseGeocode({ latitude, longitude, language: 'en' });
    const cityOrLocality = data.city || data.locality || '';
    const region = data.principalSubdivision || '';
    const country = data.countryName || '';
    const label = [cityOrLocality, region, country].filter(Boolean).join(', ');
    document.querySelector('#place').textContent = label;
  } catch (err) {
    console.error(err);
    document.querySelector('#place').textContent = 'Location unavailable';
  }
}
detectPlaceName();

curl test


curl "https://api.bigdatacloud.net/data/reverse-geocode-client?latitude=-33.8567844&longitude=151.2152967&localityLanguage=en"

What to do next

Share