Catalog

Get map detail with regions

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.

get/v1/maps/{mapId}

Request

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

Path parameters

mapIdstring required

The map's id (slug) from GET /v1/maps.

Query parameters

qstring

Case- and diacritic-insensitive substring filter over each region's key, title and accepted aliases. Matching is wide, but the response still prints only key and title.

offsetinteger

Skip this many matching regions.

limitinteger

Return at most this many regions. Omit for all of them.

Response

Map detail.

idstring

The map's slug. The same id GET /v1/maps prints, even when the request used an alias.

titlestring
regionTypestring nullable
regionTypePluralstring nullable
layersLayerId[]

Extra layers this map ships, renderable via the layers request field.

regionCountinteger

Regions in the whole map, regardless of q/offset/limit.

labelsboolean

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.

Example response

{
  "id": "united-states",
  "regionCount": 51,
  "regions": [
    {
      "key": "US-CA",
      "title": "California"
    }
  ],
  "page": {
    "matched": 51
  }
}

Changes

No recorded changes to this operation across all 3 revisions of this API.