@bigdatacloudapi/vue-reverse-geocode-client

Vue composable for free reverse geocoding — get city, country, and locality from GPS coordinates with automatic IP geolocation fallback. No API key needed.

---

Install

npm install @bigdatacloudapi/vue-reverse-geocode-client

yarn add @bigdatacloudapi/vue-reverse-geocode-client

pnpm add @bigdatacloudapi/vue-reverse-geocode-client

Quick Start

<script setup>
import { useGeoLocation } from '@bigdatacloudapi/vue-reverse-geocode-client';

const { data, loading, error, source } = useGeoLocation();
</script>

<template>
  <p v-if="loading">Detecting location...</p>
  <p v-else-if="error">Error: {{ error }}</p>
  <div v-else>
    <h1>📍 {{ data?.city }}, {{ data?.countryName }}</h1>
    <p>Detected via: {{ source }}</p>
  </div>
</template>

That's it. No API key, no configuration, no backend required.

---

How It Works

1. GPS first — requests the browser's Geolocation API (enableHighAccuracy: true)
2. IP fallback — if the user denies GPS or it's unavailable, the API automatically geolocates by IP address
3. Reverse geocode — coordinates (or IP) are resolved to a full locality via BigDataCloud's free API

No server-side proxy needed — the API is called directly from the browser.

---

API

useGeoLocation(options?)

The main composable. Call it in <script setup> or inside setup().

Options

Option	Type	Default	Description
language	string	Browser language	Locality language code (e.g. 'en', 'de', 'zh')
manual	boolean	false	If true, don't fetch on mount — call refresh() manually
timeout	number	10000	GPS timeout in milliseconds

Returns

Property	Type	Description
data	Ref<LocationData | null>	The full location response
loading	Ref<boolean>	true while fetching
error	Ref<string | null>	Error message, if any
source	Ref<'gps' | 'ip' | null>	How the location was detected
refresh	() => void	Re-trigger the location lookup

Parameters

Parameter	Type	Description
coords	{ latitude: number, longitude: number }	Optional. Omit for IP-based geolocation.
language	string	Optional locality language code.

LocationData

interface LocationData {
  latitude: number;
  longitude: number;
  lookupSource: string;
  continent: string;
  continentCode: string;
  countryName: string;
  countryCode: string;
  principalSubdivision: string;
  principalSubdivisionCode: string;
  city: string;
  locality: string;
  postcode: string;
  plusCode: string;
  localityInfo: {
    administrative: LocalityInfoEntry[];
    informative: LocalityInfoEntry[];
  };
}

---

Examples

Multi-language

<script setup>
import { useGeoLocation } from '@bigdatacloudapi/vue-reverse-geocode-client';

// Get locality names in German
const { data, loading } = useGeoLocation({ language: 'de' });
</script>

Manual trigger

<script setup>
import { useGeoLocation } from '@bigdatacloudapi/vue-reverse-geocode-client';

const { data, loading, refresh } = useGeoLocation({ manual: true });
</script>

<template>
  <button @click="refresh" :disabled="loading">
    {{ loading ? 'Detecting...' : 'Detect my location' }}
  </button>
  <p v-if="data">{{ data.city }}, {{ data.countryName }}</p>
</template>

Nuxt 3

Works out of the box in Nuxt 3 — no plugins or special configuration needed. Just import and use:

<!-- pages/index.vue -->
<script setup>
import { useGeoLocation } from '@bigdatacloudapi/vue-reverse-geocode-client';

const { data, loading, error, source } = useGeoLocation();
</script>

<template>
  <div>
    <p v-if="loading">Detecting location...</p>
    <p v-else-if="error">{{ error }}</p>
    <div v-else-if="data">
      <h1>{{ data.city }}, {{ data.countryName }}</h1>
      <p>{{ data.continent }} · {{ data.principalSubdivision }}</p>
      <p>Source: {{ source }}</p>
    </div>
  </div>
</template>

Note: Since this composable uses navigator.geolocation, it only runs client-side. During SSR, data will be null and loading will be false until the component hydrates in the browser.

Using the standalone function

// In a Pinia store, utility, or anywhere
import { reverseGeocode } from '@bigdatacloudapi/vue-reverse-geocode-client';

export async function getLocationLabel(): Promise<string> {
  const loc = await reverseGeocode();
  return `${loc.city}, ${loc.countryName}`;
}

---

Why BigDataCloud?

• Free — no API key, no sign-up, no credit card
• Fast — global CDN, sub-100ms responses
• Accurate — powered by BigDataCloud's proprietary geocoding database
• Privacy-friendly — no cookies, no tracking, no personal data stored

---

Fair Use Policy

This library uses BigDataCloud's free client-side reverse geocoding API (api.bigdatacloud.net), governed by the Fair Use Policy.

This API is for resolving the current, real-time location of the calling device only.

Key rules:

• Client-side only — requests must originate directly from the device being located, not from a server or automated script
• Real-time coordinates only — only live GPS/WiFi coordinates obtained at the moment of the call are permitted. Pre-stored, cached, or externally-sourced coordinates are strictly not allowed
• User consent required — coordinates must be obtained via platform geolocation APIs with the user's explicit permission

Violations result in a 402 error and your IP address being banned.

If you need to geocode coordinates you already have, or need server-side geocoding, use the Reverse Geocoding API with a free API key instead — it includes 50,000 free queries per month.

---

Need More?

BigDataCloud offers a full suite of geolocation and data APIs:

• 🌐 IP Geolocation API — detailed IP-to-location with confidence scores
• 🗺️ Server-side Reverse Geocoding — high-volume, authenticated API
• 📦 @bigdatacloudapi/react-reverse-geocode-client — React version of this package
• 🔧 @bigdatacloudapi/mcp-server — MCP server for AI agents

Visit bigdatacloud.com for the full API catalog.

---

License

MIT © BigDataCloud Pty Ltd