---
title: "Geo Leads"
method: GET
path: "/api/v1/leads/geo"
tags: ["leads", "leads"]
---

# Geo Leads

`GET /api/v1/leads/geo`

## Request

- Base URL: `https://app.goodleads.club` (the document declares no server; this is the origin it was published from)
- URL: `https://app.goodleads.club/api/v1/leads/geo`
- Auth: API key in header `X-API-Key`

Trimmed map-plotting payload — lat/lon + minimum columns for pin rendering.

Powers the Map View page (docs/product/prds/MAP_VIEW_FL_MVP.md). Same
filter contract as ``GET /leads`` so the shared filter chip-bar wires
into both pages identically (Rule 12 — one filter contract, three
interfaces).

Requires ``latitude IS NOT NULL`` — records without geocoded coordinates
are summarized in the response's ``no_coords_total`` so the map footer
can show "X entities not shown — no coordinates" without a second call.

No pagination: returns the full filter scope in one shot (capped at
GEO_LEADS_CAP per services.leads_query). Coordinates are rounded to
5 decimals (~1m precision) to shave ~10% off the wire size without
visible map degradation.

Cached privately for 60s. The URL — including the filters JSON — is
the cache key, so same-scope re-navigations within a minute (tab
refresh, state switch back) hit the browser cache instead of re-
transferring the full payload. Filter changes naturally bust by
producing a different URL.

## Query parameters

- `state` string, nullable
- `filters` string, nullable: JSON-encoded filter array
- `include_non_operating` boolean: Include records the Contact Intelligence brain marked enrichment_strategy='hold'. Default False — sellable inventory only, matching Browse.
- `include_existing` boolean: Include existing businesses with a new filing: companies opening a location here, local owners who formed their company in another state, businesses back in business, established businesses under a new entity, moved, or with a new trade name. Default False — Just started only (a brand-new business), matching every file sold as new businesses. Naming a filing_kind in `filters` implies it.
- `include_registrations` boolean: Deprecated alias of include_existing (kept one release so saved links resolve).
- `bbox` string, nullable: Viewport bbox as 'west,south,east,north' (lon,lat lon,lat). When set, restricts pins to lat/lon inside the rectangle. Map View sends the current viewport on every moveend/zoomend; agents fetching whole-state payloads should omit it.
- `include_no_coords` boolean: Compute no_coords_total (count of matching leads without coordinates). Constant per filter scope — the Map View passes false on viewport-only refreshes to skip the COUNT; the response then has no_coords_total=null.

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/goodleads/apis/formation-gtm-api.md) · [All operations](https://skmtc.dev/goodleads/apis/formation-gtm-api/llms.txt) · [OpenAPI document](https://skmtc.dev/goodleads/apis/formation-gtm-api/revisions/2068d13a82cf?raw)