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

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?

• Free, no key, no sign-up — ideal for websites and client apps (Fair Use Policy applies).
• Privacy-friendly — no personal identifiers; see Why is the Reverse Geocoding API free?
• Global coverage — city/suburb-level detail with multilingual support.
• Optional fallback — if users deny permission, integrate an IP-based fallback as described here: Free client-side reverse geocoding with IP fallback.

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

• Read the Fair Use Policy.
• Understand why the API is free.
• Need server-side processing or dev testing? Use the server-side API.
• See our broader Reverse Geocoding and IP Geolocation services.