---
title: "Get map detail with regions"
method: GET
path: "/v1/maps/{mapId}"
tags: ["Catalog"]
---

# Get map detail with regions

`GET /v1/maps/{mapId}`

## Request

- Base URL: `https://api.ultimaps.com`
- URL: `https://api.ultimaps.com/v1/maps/{mapId}`
- Auth: none required

Full detail for one map: its layers and every region as `{key, title}`. `key` is the region's code in the map's primary scheme (ISO 3166-2, FIPS, ZCTA, GSS, …), or its title where the scheme publishes no code for it. It is the recommended key for `choropleth.values`, `categories.values` and `regions`. The render endpoint also accepts titles, common aliases (USPS abbreviations, alternate names) and typos, so you rarely need this call before rendering. `q` filters regions by key, title or any accepted alias, so a search for "CA" finds California even though only `US-CA` is emitted. `offset` and `limit` page through large maps (US counties has 3,143 regions). Without them you get every region, and nothing is truncated silently. No authentication. Cached for one hour (`Cache-Control: public, max-age=3600`). Private workspace maps are not exposed here.

## Path parameters

- `mapId` string, required

## Query parameters

- `q` string
- `offset` integer
- `limit` integer

## Response `200`

Map detail.

- MapDetail
  - `id` string: The map's slug. The same id `GET /v1/maps` prints, even when the request used an alias.
  - `title` string
  - `regionType` string, nullable
  - `regionTypePlural` string, nullable
  - `layers` LayerId[]: Extra layers this map ships, renderable via the `layers` request field.
  - `regionCount` integer: Regions in the whole map, regardless of `q`/`offset`/`limit`.
  - `labels` boolean: Whether this map ships curated region labels, which is what `style.labels` draws. Coverage varies by map, and the flag only says whether any exist.
  - `regions` object[]: The requested page of regions. Aliases are accepted as render input but never emitted here. `key` is the one identifier the API documents and prints.
    - `key` string, required: The region's code in the map's primary scheme (ISO 3166-2, FIPS, ZCTA, GSS, …), or its title where the scheme publishes no code. Unique within the map. The recommended render key. Never empty.
    - `title` string, required
  - `page` object
    - `offset` integer, required
    - `limit` integer, nullable, required: The effective `limit`, or `null` when every matching region was returned.
    - `matched` integer, required: Regions matching `q` (all of them when `q` is absent) before paging.

## Other responses

- `400`: The request failed validation.
- `404`: The mapId does not exist (or is not accessible).
- `500`: Unexpected server error. Safe to retry with backoff.

---

[API](https://skmtc.dev/ultimaps/apis/ultimaps-public-api.md) · [All operations](https://skmtc.dev/ultimaps/apis/ultimaps-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ultimaps/apis/ultimaps-public-api/revisions/b913e49453e5?raw)