@quantavoxel/latlng-extract 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wawan Julianto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# @quantavoxel/latlng-extract
+
+Extract latitude and longitude coordinates from Google Maps short links and full URLs.
+
+[![npm version](https://img.shields.io/npm/v/@quantavoxel/latlng-extract)](https://www.npmjs.com/package/@quantavoxel/latlng-extract)
+[![license](https://img.shields.io/npm/l/@quantavoxel/latlng-extract)](./LICENSE)
+[![node](https://img.shields.io/node/v/@quantavoxel/latlng-extract)](https://nodejs.org)
+
+```ts
+import { extract } from "@quantavoxel/latlng-extract";
+
+const result = await extract("https://maps.app.goo.gl/ETAXbutPiLGMj2bA9");
+// { lat: -5.1477, lng: 119.4327, resolvedUrl: "https://www.google.com/maps/..." }
+```
+
+---
+
+## Features
+
+- Resolves Google Maps short links (`maps.app.goo.gl`, `goo.gl/maps`)
+- Supports full Google Maps URLs (`maps.google.com`, `www.google.com/maps`)
+- Typed error codes for clean error handling
+- Configurable timeout, User-Agent, and max redirects
+- Zero config — works out of the box
+
+## Installation
+
+```bash
+npm install @quantavoxel/latlng-extract
+```
+
+## Usage
+
+### Basic
+
+```ts
+import { extract } from "@quantavoxel/latlng-extract";
+
+const result = await extract("https://maps.app.goo.gl/ETAXbutPiLGMj2bA9");
+
+console.log(result.lat);         // -5.1477
+console.log(result.lng);         // 119.4327
+console.log(result.resolvedUrl); // https://www.google.com/maps/...
+```
+
+### With options
+
+```ts
+import { extract } from "@quantavoxel/latlng-extract";
+
+const result = await extract("https://maps.app.goo.gl/ETAXbutPiLGMj2bA9", {
+  timeout: 5000,
+  userAgent: "MyApp/1.0",
+  maxRedirects: 5,
+});
+```
+
+### Error handling
+
+```ts
+import { extract } from "@quantavoxel/latlng-extract";
+import type { ExtractError } from "@quantavoxel/latlng-extract";
+
+try {
+  const result = await extract("https://maps.app.goo.gl/ETAXbutPiLGMj2bA9");
+  console.log(result);
+} catch (err) {
+  const e = err as ExtractError;
+
+  switch (e.code) {
+    case "INVALID_URL":
+      console.error("URL is not a valid Google Maps link");
+      break;
+    case "RESOLVE_FAILED":
+      console.error("Link is broken or expired");
+      break;
+    case "COORDS_NOT_FOUND":
+      console.error("Could not find coordinates in the resolved URL");
+      break;
+    case "TIMEOUT":
+      console.error("Request timed out");
+      break;
+  }
+}
+```
+
+## API
+
+### `extract(url, options?)`
+
+Resolves a Google Maps URL and extracts its coordinates.
+
+**Parameters**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `url` | `string` | ✅ | Google Maps URL (short or full) |
+| `options` | `ExtractOptions` | ❌ | Optional configuration |
+
+**Returns** `Promise<ExtractResult>`
+
+---
+
+### `ExtractResult`
+
+```ts
+interface ExtractResult {
+  lat: number;         // Latitude
+  lng: number;         // Longitude
+  resolvedUrl: string; // Final URL after redirect
+}
+```
+
+### `ExtractOptions`
+
+```ts
+interface ExtractOptions {
+  userAgent?: string;    // Default: "Mozilla/5.0 (compatible; latlng-extract/1.0)"
+  timeout?: number;      // In milliseconds. Default: 10000
+  maxRedirects?: number; // Default: 10
+}
+```
+
+### `ExtractError`
+
+```ts
+interface ExtractError extends Error {
+  code: "INVALID_URL" | "RESOLVE_FAILED" | "COORDS_NOT_FOUND" | "TIMEOUT";
+  url: string; // The original URL passed to extract()
+}
+```
+
+## Supported URL formats
+
+| Format | Example |
+|---|---|
+| Short link | `https://maps.app.goo.gl/ETAXbutPiLGMj2bA9` |
+| Legacy short link | `https://goo.gl/maps/abc123` |
+| Full URL | `https://maps.google.com/maps?q=-5.1477,119.4327` |
+| Full URL (www) | `https://www.google.com/maps/place/...@-5.1477,119.4327` |
+
+## Requirements
+
+- Node.js >= 18.0.0
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { ExtractResult, ExtractOptions, ExtractError } from "./type.ts";
+export declare function extract(url: string, options?: ExtractOptions): Promise<ExtractResult>;
+export type { ExtractResult, ExtractOptions, ExtractError };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAmD7E,wBAAsB,OAAO,CAC3B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CAkDxB;AAED,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,73 @@
+import axios from "axios";
+const COORD_PATTERNS = [
+    /@(-?\d+\.\d+),(-?\d+\.\d+)/, // @lat,lng
+    /!3d(-?\d+\.\d+)!4d(-?\d+\.\d+)/, // !3dLAT!4dLNG
+    /ll=(-?\d+\.\d+),(-?\d+\.\d+)/, // ll=lat,lng
+    /q=(-?\d+\.\d+),(-?\d+\.\d+)/, // q=lat,lng
+    /center=(-?\d+\.\d+),(-?\d+\.\d+)/, // center=lat,lng
+];
+const SUPPORTED_HOSTS = [
+    "maps.app.goo.gl",
+    "goo.gl",
+    "maps.google.com",
+    "www.google.com",
+];
+function createError(message, code, url) {
+    const err = new Error(message);
+    err.code = code;
+    err.url = url;
+    return err;
+}
+function isValidGoogleMapsUrl(url) {
+    try {
+        const { hostname, pathname } = new URL(url);
+        if (hostname === "goo.gl" && !pathname.startsWith("/maps"))
+            return false;
+        return SUPPORTED_HOSTS.includes(hostname);
+    }
+    catch {
+        return false;
+    }
+}
+function parseCoords(text) {
+    for (const pattern of COORD_PATTERNS) {
+        const match = text.match(pattern);
+        if (match) {
+            return {
+                lat: parseFloat(match[1]),
+                lng: parseFloat(match[2]),
+            };
+        }
+    }
+    return null;
+}
+export async function extract(url, options = {}) {
+    const { userAgent = "Mozilla/5.0 (compatible; latlng-extract/1.0)", timeout = 10000, maxRedirects = 10, } = options;
+    if (!isValidGoogleMapsUrl(url)) {
+        throw createError(`Invalid or unsupported URL: "${url}"`, "INVALID_URL", url);
+    }
+    let resolvedUrl;
+    let responseText;
+    try {
+        const response = await axios.get(url, {
+            headers: { "User-Agent": userAgent },
+            timeout,
+            maxRedirects,
+        });
+        resolvedUrl = response.request?.res?.responseUrl ?? url;
+        responseText = typeof response.data === "string" ? response.data : "";
+    }
+    catch (err) {
+        if (axios.isAxiosError(err) && err.code === "ECONNABORTED") {
+            throw createError(`Request timed out for "${url}"`, "TIMEOUT", url);
+        }
+        throw createError(`Failed to resolve URL: ${err.message}`, "RESOLVE_FAILED", url);
+    }
+    // Try resolved URL first (most reliable), then fallback to HTML body
+    const coords = parseCoords(resolvedUrl) ?? parseCoords(responseText);
+    if (!coords) {
+        throw createError(`Could not extract coordinates from "${resolvedUrl}"`, "COORDS_NOT_FOUND", url);
+    }
+    return { ...coords, resolvedUrl };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/tes.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tes.d.ts.map

package/dist/tes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tes.d.ts","sourceRoot":"","sources":["../src/tes.ts"],"names":[],"mappings":""}

package/dist/tes.js

@@ -0,0 +1,36 @@
+import { extract } from "./index.js";
+async function run() {
+    const urls = [
+        "https://maps.app.goo.gl/ETAXbutPiLGMj2bA9", // valid
+        "https://maps.app.goo.gl/123456", // invalid
+        "https://invalid-url.com", // not google maps
+    ];
+    for (const url of urls) {
+        console.log(`\nTesting: ${url}`);
+        try {
+            const result = await extract(url);
+            console.log("✅ Success:", result);
+        }
+        catch (err) {
+            const e = err;
+            switch (e.code) {
+                case "INVALID_URL":
+                    console.error("❌ Invalid URL:", e.message);
+                    break;
+                case "RESOLVE_FAILED":
+                    console.error("❌ URL not found or expired:", e.message);
+                    break;
+                case "COORDS_NOT_FOUND":
+                    console.error("❌ No coordinates found in:", e.url);
+                    break;
+                case "TIMEOUT":
+                    console.error("❌ Request timed out:", e.url);
+                    break;
+                default:
+                    console.error("❌ Unknown error:", e.message);
+            }
+        }
+    }
+}
+run();
+//# sourceMappingURL=tes.js.map

package/dist/tes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tes.js","sourceRoot":"","sources":["../src/tes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAGrC,KAAK,UAAU,GAAG;IAChB,MAAM,IAAI,GAAG;QACX,2CAA2C,EAAE,QAAQ;QACrD,gCAAgC,EAAE,UAAU;QAC5C,yBAAyB,EAAE,kBAAkB;KAC9C,CAAC;IAEF,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,OAAO,CAAC,GAAG,CAAC,cAAc,GAAG,EAAE,CAAC,CAAC;QAEjC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;YAClC,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,GAAG,GAAmB,CAAC;YAE9B,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;gBACf,KAAK,aAAa;oBAChB,OAAO,CAAC,KAAK,CAAC,gBAAgB,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;oBAC3C,MAAM;gBACR,KAAK,gBAAgB;oBACnB,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;oBACxD,MAAM;gBACR,KAAK,kBAAkB;oBACrB,OAAO,CAAC,KAAK,CAAC,4BAA4B,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;oBACnD,MAAM;gBACR,KAAK,SAAS;oBACZ,OAAO,CAAC,KAAK,CAAC,sBAAsB,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;oBAC7C,MAAM;gBACR;oBACE,OAAO,CAAC,KAAK,CAAC,kBAAkB,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;YACjD,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED,GAAG,EAAE,CAAC"}

package/dist/type.d.ts

@@ -0,0 +1,19 @@
+export interface ExtractResult {
+    lat: number;
+    lng: number;
+    resolvedUrl: string;
+}
+export interface ExtractOptions {
+    /** Custom User-Agent header. Default: Mozilla/5.0 */
+    userAgent?: string;
+    /** Request timeout in milliseconds. Default: 10000 */
+    timeout?: number;
+    /** Max redirects to follow. Default: 10 */
+    maxRedirects?: number;
+}
+export type SupportedUrl = "maps.app.goo.gl" | "goo.gl/maps" | "maps.google.com" | "www.google.com/maps";
+export interface ExtractError extends Error {
+    code: "INVALID_URL" | "RESOLVE_FAILED" | "COORDS_NOT_FOUND" | "TIMEOUT";
+    url: string;
+}
+//# sourceMappingURL=type.d.ts.map

package/dist/type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../src/type.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,YAAY,GACpB,iBAAiB,GACjB,aAAa,GACb,iBAAiB,GACjB,qBAAqB,CAAC;AAE1B,MAAM,WAAW,YAAa,SAAQ,KAAK;IACzC,IAAI,EAAE,aAAa,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,SAAS,CAAC;IACxE,GAAG,EAAE,MAAM,CAAC;CACb"}

package/dist/type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=type.js.map

package/dist/type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.js","sourceRoot":"","sources":["../src/type.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@quantavoxel/latlng-extract",
+  "version": "1.0.2",
+  "description": "Extract latitude and longitude coordinates from Google Maps short links (maps.app.goo.gl)",
+  "keywords": [
+    "google-maps",
+    "coordinates",
+    "latitude",
+    "longitude",
+    "latlng",
+    "gps",
+    "maps",
+    "short-link",
+    "goo.gl",
+    "geolocation",
+    "extract"
+  ],
+  "homepage": "https://github.com/QuantaVoxel/latlng-extract#readme",
+  "bugs": {
+    "url": "https://github.com/QuantaVoxel/latlng-extract/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/QuantaVoxel/latlng-extract.git"
+  },
+  "license": "MIT",
+  "author": "Quantavoxel <developer@quantavoxel.digital>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "dist/index.cjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/tes.ts",
+    "prepublishOnly": "npm run build",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "axios": "^1.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.22.4",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "module": "dist/index.js",
+  "allowScripts": {
+    "esbuild@0.28.0": true
+  }
+}