---
title: "List available maps"
method: GET
path: "/v1/maps"
tags: ["Catalog"]
---

# List available maps

`GET /v1/maps`

## Request

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

The full public map catalog: every map you can render, with its id, title, what a "region" means on it, extra layers, and region count. This is the discovery entry point, since every render needs a `mapId` from here. Map ids are stable slugs (`united-states`, `europe`, `world-equal-earth`) that always point at the current edition of a map. An id is the map's slug on ultimaps.com, the last path segment of its page rather than the whole URL. `q` filters the catalog by id, title, region type or category (case- and diacritic- insensitive substring, and it also matches ids you may have seen in Studio URLs). No authentication. Cached for one hour (`Cache-Control: public, max-age=3600`). Not paginated: `data` is every matching map, and `meta` reports `matched` against `total` so you can see what a filter removed. Private workspace maps are never listed here, even with a key. They stay renderable by id with a key from their workspace.

## Query parameters

- `q` string

## Response `200`

Catalog envelope.

- object
  - `data` CatalogMap[], required
    - `id` string: Stable slug, the `mapId` for every other endpoint. Points at the current edition of the map. It is the map's slug on ultimaps.com: the last path segment of its page, not the whole URL.
    - `title` string
    - `regionType` string, nullable
    - `layers` LayerId[]: Extra layers this map ships, renderable via the `layers` request field.
    - `regionCount` integer
    - `labels` boolean: Whether this map ships curated region labels, which is what `style.labels` draws. Most county and district maps have none.
  - `meta` object, required
    - `matched` integer, required: Maps in `data` (after `q`).
    - `total` integer, required: Maps in the whole catalog, regardless of `q`.

## Other responses

- `400`: The request failed validation.
- `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)