@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

This package uses BigDataCloud's free reverse geocoding API. It's intended for light, client-side use — perfect for showing a visitor their detected city, personalizing content, or building location-aware UIs.

For high-volume, server-side, or commercial use, please use an API key.

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