Skip to main content

​
google-maps-link-parser

google-maps-link-parser is a Bun-first TypeScript library for working with public shared Google Maps URLs. It does three things well:

Parse

Pure URL analysis with zero network calls.

Unfurl

SSRF-safe redirect following for maps.app.goo.gl and goo.gl/maps.

Enrich

Optional Google API lookups with explicit cost controls.

​
Why this package exists

Real Google Maps links are inconsistent in the wild. You will see:
  • coordinate views like @24.7136,46.6753,15z
  • dropped pins like ?q=24.7136,46.6753
  • legacy center parameters like ll=24.7136,46.6753
  • data=!3d...!4d... payloads
  • place pages with ftid identifiers
  • directions and search URLs
  • short links that require multiple redirects before they become useful
This package normalizes all of that into one stable top-level envelope so your app can depend on a single shape instead of a pile of regexes.

​
Design principles

The package only targets public shared URLs. Private, authenticated, or unsupported Google share flows fail clearly instead of being guessed.
  • Early exits and typed boundaries
  • Direct parsing before network work
  • Strong hostname validation on every redirect hop
  • Explicit source attribution for coordinates and metadata
  • Raw artifacts only when you opt in

​
What you get back

Every mode returns the same top-level object: 
interface GoogleMapsEnvelope {
  status: "ok" | "error";
  mode: "minimal" | "unfurl" | "enriched";
  intent:
    | "coordinates"
    | "place"
    | "search"
    | "directions"
    | "map"
    | "streetview"
    | "unknown";
  input: InputMetadata;
  resolution: ResolutionMetadata;
  identifiers: {
    featureId: string | null;
    placeId: string | null;
    plusCode: PlusCode | null;
  };
  location: NormalizedSection<LocationData>;
  place: NormalizedSection<PlaceData>;
  route: NormalizedSection<RouteData>;
  query: NormalizedSection<QueryData>;
  mapView: NormalizedSection<MapViewData>;
  raw?: RawArtifacts;
}
That stable envelope is the product. Modes only change how much work the library is allowed to do.

​
Start here

Install

Bun, npm, and pnpm setup.

Quick start

Parse a direct Maps URL and unfurl a short link.