> ## Documentation Index
> Fetch the complete documentation index at: https://gmlp.kdco.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick start

> Parse a direct URL, unfurl a short link, and understand when to enrich.

## Parse a direct Google Maps URL

```ts theme={null}
import { parseGoogleMapsUrl } from "google-maps-link-parser";

const result = parseGoogleMapsUrl("https://www.google.com/maps/@24.7136,46.6753,15z");

if (result.status === "error") {
  throw new Error(result.error?.message ?? "Unexpected parse failure");
}

console.log(result.intent); // => "coordinates"

console.log(result.location.value);
```

Output

```txt theme={null}
{ latitude: 24.7136, longitude: 46.6753, source: "at-pattern", accuracy: "exact" }
```

## Unfurl a short link safely

```ts theme={null}
import { unfurlGoogleMapsUrl } from "google-maps-link-parser";

const redirectSteps = [
  {
    status: 302,
    location: "https://www.google.com/maps/@24.7136,46.6753,15z",
  },
  { status: 200 },
];

let redirectIndex = 0;
const mockFetch = async () => {
  const step = redirectSteps[redirectIndex++];
  if (!step) {
    throw new Error("Unexpected fetch call");
  }

  return new Response("", {
    status: step.status,
    headers: step.location ? { Location: step.location } : {},
  });
};

const result = await unfurlGoogleMapsUrl("https://maps.app.goo.gl/abc123?g_st=ic", {
  fetch: mockFetch,
  raw: { enabled: true },
});

console.log(result.resolution.status); // => "resolved"
console.log(result.resolution.resolvedUrl); // => "https://www.google.com/maps/@24.7136,46.6753,15z"
console.log(result.raw?.redirects?.hops);
```

Output

```txt theme={null}
[
  {
    requestUrl: "https://maps.app.goo.gl/abc123",
    responseStatus: 302,
    locationHeader: "https://www.google.com/maps/@24.7136,46.6753,15z"
  },
  {
    requestUrl: "https://www.google.com/maps/@24.7136,46.6753,15z",
    responseStatus: 200,
    locationHeader: null
  }
]
```

## Enrich only when you need more data

```ts theme={null}
import { analyzeGoogleMapsUrl } from "google-maps-link-parser";

const result = await analyzeGoogleMapsUrl("https://www.google.com/maps?q=Malaz+Riyadh", {
  mode: "enriched",
  enrich: {
    policy: "when-needed",
    google: {
      apiKey: process.env.GOOGLE_MAPS_API_KEY ?? "",
      enablePlaces: true,
      enableDirections: false,
    },
  },
});
```

<Warning>
  `enriched` mode is opt-in because provider calls can cost money. Keep the default policy
  as `when-needed` unless you have a strong reason to force `always`.
</Warning>