@bigdatacloudapi/vue-reverse-geocode-client 1.0.0

package/README.md

@@ -0,0 +1,233 @@
+# @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.**
+
+[![npm](https://img.shields.io/npm/v/@bigdatacloudapi/vue-reverse-geocode-client)](https://www.npmjs.com/package/@bigdatacloudapi/vue-reverse-geocode-client)
+[![license](https://img.shields.io/npm/l/@bigdatacloudapi/vue-reverse-geocode-client)](https://github.com/bigdatacloudapi/vue-reverse-geocode-client/blob/main/LICENSE)
+
+---
+
+## Install
+
+```bash
+npm install @bigdatacloudapi/vue-reverse-geocode-client
+```
+
+```bash
+yarn add @bigdatacloudapi/vue-reverse-geocode-client
+```
+
+```bash
+pnpm add @bigdatacloudapi/vue-reverse-geocode-client
+```
+
+## Quick Start
+
+```vue
+<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](https://www.bigdatacloud.com/free-api/free-reverse-geocode-to-city-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 |
+
+### `reverseGeocode(coords?, language?)`
+
+Standalone async function — no Vue dependency needed. Great for one-off lookups or use outside components.
+
+```ts
+import { reverseGeocode } from '@bigdatacloudapi/vue-reverse-geocode-client';
+
+// With coordinates
+const location = await reverseGeocode({ latitude: -34.9285, longitude: 138.6007 });
+console.log(location.city); // "Adelaide"
+
+// IP-based fallback (no coordinates)
+const ipLocation = await reverseGeocode();
+console.log(ipLocation.countryName);
+```
+
+#### Parameters
+
+| Parameter | Type | Description |
+|---|---|---|
+| `coords` | `{ latitude: number, longitude: number }` | Optional. Omit for IP-based geolocation. |
+| `language` | `string` | Optional locality language code. |
+
+### `LocationData`
+
+```ts
+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
+
+```vue
+<script setup>
+import { useGeoLocation } from '@bigdatacloudapi/vue-reverse-geocode-client';
+
+// Get locality names in German
+const { data, loading } = useGeoLocation({ language: 'de' });
+</script>
+```
+
+### Manual trigger
+
+```vue
+<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:
+
+```vue
+<!-- 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
+
+```ts
+// 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](https://www.bigdatacloud.com/pricing).
+
+---
+
+## Need More?
+
+BigDataCloud offers a full suite of geolocation and data APIs:
+
+- 🌐 **[IP Geolocation API](https://www.bigdatacloud.com/ip-geolocation)** — detailed IP-to-location with confidence scores
+- 🗺️ **[Server-side Reverse Geocoding](https://www.bigdatacloud.com/reverse-geocoding)** — high-volume, authenticated API
+- 📦 **[@bigdatacloudapi/react-reverse-geocode-client](https://www.npmjs.com/package/@bigdatacloudapi/react-reverse-geocode-client)** — React version of this package
+- 🔧 **[@bigdatacloudapi/mcp-server](https://www.npmjs.com/package/@bigdatacloudapi/mcp-server)** — MCP server for AI agents
+
+Visit [bigdatacloud.com](https://www.bigdatacloud.com) for the full API catalog.
+
+---
+
+## License
+
+MIT © [BigDataCloud Pty Ltd](https://www.bigdatacloud.com)

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+import type { Ref } from 'vue';
+export interface LocalityInfoEntry {
+    order: number;
+    adminLevel: number;
+    name: string;
+    description: string;
+    isoName: string;
+    isoCode: string;
+    wikidataId: string;
+    geonameId: number;
+}
+export 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[];
+    };
+}
+export interface UseGeoLocationOptions {
+    /** Language for locality names (e.g. 'en', 'de', 'zh'). Default: browser language. */
+    language?: string;
+    /** If true, don't fetch on mount — call refresh() manually. */
+    manual?: boolean;
+    /** GPS timeout in milliseconds. Default: 10000. */
+    timeout?: number;
+}
+export interface UseGeoLocationReturn {
+    data: Ref<LocationData | null>;
+    loading: Ref<boolean>;
+    error: Ref<string | null>;
+    source: Ref<'gps' | 'ip' | null>;
+    refresh: () => void;
+}
+/**
+ * Reverse-geocode coordinates (or fall back to IP geolocation if none provided).
+ *
+ * @param coords  Optional `{ latitude, longitude }`.
+ * @param language  Optional locality language code.
+ * @returns LocationData from the BigDataCloud API.
+ */
+export declare function reverseGeocode(coords?: {
+    latitude: number;
+    longitude: number;
+}, language?: string): Promise<LocationData>;
+/**
+ * Vue composable for free reverse geocoding.
+ *
+ * Tries the browser Geolocation API first (GPS / Wi-Fi), then falls back to
+ * IP-based geolocation — no API key needed.
+ */
+export declare function useGeoLocation(options?: UseGeoLocationOptions): UseGeoLocationReturn;
+/** Alias for backward compatibility. */
+export declare const useLocation: typeof useGeoLocation;

package/dist/index.js

@@ -0,0 +1,91 @@
+import { ref, onMounted } from 'vue';
+const API_URL = 'https://api.bigdatacloud.net/data/reverse-geocode-client';
+// ── Standalone function ────────────────────────────────────────────────────
+/**
+ * Reverse-geocode coordinates (or fall back to IP geolocation if none provided).
+ *
+ * @param coords  Optional `{ latitude, longitude }`.
+ * @param language  Optional locality language code.
+ * @returns LocationData from the BigDataCloud API.
+ */
+export async function reverseGeocode(coords, language) {
+    const params = new URLSearchParams();
+    if (coords) {
+        params.set('latitude', String(coords.latitude));
+        params.set('longitude', String(coords.longitude));
+    }
+    if (language) {
+        params.set('localityLanguage', language);
+    }
+    const url = `${API_URL}?${params.toString()}`;
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`Reverse geocode request failed: ${res.status} ${res.statusText}`);
+    }
+    return res.json();
+}
+// ── Composable ─────────────────────────────────────────────────────────────
+/**
+ * Vue composable for free reverse geocoding.
+ *
+ * Tries the browser Geolocation API first (GPS / Wi-Fi), then falls back to
+ * IP-based geolocation — no API key needed.
+ */
+export function useGeoLocation(options = {}) {
+    const { language, manual = false, timeout = 10000 } = options;
+    const data = ref(null);
+    const loading = ref(false);
+    const error = ref(null);
+    const source = ref(null);
+    async function fetchLocation(coords) {
+        loading.value = true;
+        error.value = null;
+        try {
+            const result = await reverseGeocode(coords, language);
+            data.value = result;
+            source.value = result.lookupSource === 'ip address' ? 'ip' : 'gps';
+        }
+        catch (err) {
+            error.value = err instanceof Error ? err.message : 'Unknown error';
+        }
+        finally {
+            loading.value = false;
+        }
+    }
+    function tryGps() {
+        return new Promise((resolve, reject) => {
+            if (typeof navigator === 'undefined' || !navigator.geolocation) {
+                reject(new Error('Geolocation not available'));
+                return;
+            }
+            navigator.geolocation.getCurrentPosition(resolve, reject, {
+                enableHighAccuracy: true,
+                timeout,
+                maximumAge: 0,
+            });
+        });
+    }
+    async function refresh() {
+        loading.value = true;
+        error.value = null;
+        try {
+            const position = await tryGps();
+            await fetchLocation({
+                latitude: position.coords.latitude,
+                longitude: position.coords.longitude,
+            });
+        }
+        catch {
+            // GPS failed or denied — fall back to IP geolocation
+            await fetchLocation();
+        }
+    }
+    onMounted(() => {
+        if (!manual) {
+            refresh();
+        }
+    });
+    return { data, loading, error, source, refresh };
+}
+/** Alias for backward compatibility. */
+export const useLocation = useGeoLocation;

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@bigdatacloudapi/vue-reverse-geocode-client",
+  "version": "1.0.0",
+  "description": "Vue composable for free reverse geocoding — get city, country, and locality from GPS coordinates with automatic IP geolocation fallback. No API key needed.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "vue",
+    "nuxt",
+    "composable",
+    "geolocation",
+    "reverse-geocoding",
+    "free",
+    "no-api-key",
+    "bigdatacloud"
+  ],
+  "author": "BigDataCloud Pty Ltd",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bigdatacloudapi/vue-reverse-geocode-client"
+  },
+  "peerDependencies": {
+    "vue": ">=3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vue": "^3.5.0"
+  }
+}