Reference

Cartographer API

Public, read-only endpoints for browsing maps and pulling artifacts. Click any endpoint to see parameters and a sample response.

API key authentication

Paid members can create read-only keys on the Account page. Send Authorization: Bearer crt_... or X-API-Key: crt_.... Endpoints marked Public work without a key for any map whose visibility is public.

GET /api/gallery Public (or any valid API key) ›

List every map that has been published with public visibility. No authentication required.

Sample response (200)

{
  "maps": [
    {
      "engine_version": "handcrafted-2022",
      "files": {
        "boundaries": "maps/classic-2022/boundaries.geojson",
        "decisions": "maps/classic-2022/decisions.json",
        "directory": "maps/classic-2022/directory.json",
        "populations": "maps/classic-2022/populations.json"
      },
      "label": "2022 Yigions (Classic)",
      "links": {
        "boundaries": "https://example.com/api/maps/classic-2022/boundaries.geojson",
        "directory": "https://example.com/api/maps/classic-2022/directory.json",
        "metadata": "https://example.com/api/maps/classic-2022",
        "populations": "https://example.com/api/maps/classic-2022/populations.json"
      },
      "map_id": "classic-2022",
      "owner": null,
      "parameters": {
        "source": "handcrafted-2022",
        "target": 100000000
      },
      "published_at": "2022-01-01T00:00:00Z",
      "summary": {
        "n_clusters": 78,
        "pop_max": 0,
        "pop_mean": 0,
        "pop_median": 0,
        "pop_min": 0,
        "total_pop": 7800000000
      },
      "visibility": "public"
    }
  ]
}

GET /api/maps Public (public maps only) or API key (member maps) ›

List published maps. Without an API key, only public maps are returned. With a member API key, all maps you can access are returned.

Sample response (200)

{
  "maps": [
    {
      "engine_version": "interactive-1",
      "files": {
        "boundaries": "maps/abc1234567/boundaries.geojson",
        "decisions": "maps/abc1234567/decisions.json",
        "directory": "maps/abc1234567/directory.json",
        "populations": "maps/abc1234567/populations.json"
      },
      "label": "Cartographer map abc1234567",
      "links": {
        "boundaries": "https://example.com/api/maps/abc1234567/boundaries.geojson",
        "directory": "https://example.com/api/maps/abc1234567/directory.json",
        "metadata": "https://example.com/api/maps/abc1234567",
        "populations": "https://example.com/api/maps/abc1234567/populations.json"
      },
      "map_id": "abc1234567",
      "owner": "you@example.com",
      "parameters": {
        "target": 1000000
      },
      "published_at": "2026-04-27T12:00:00Z",
      "summary": {
        "n_clusters": 42,
        "total_pop": 42000000
      },
      "visibility": "public"
    }
  ]
}

GET /api/maps/<map_id> Public (if map is public) or API key ›

Return metadata, summary, and artifact URLs for a single map. Public maps require no auth; private maps require a member API key.

Parameters

Name	In	Type	Description
map_id	path	string	Map identifier (e.g. classic-2022).

Sample response (200)

{
  "engine_version": "handcrafted-2022",
  "files": {
    "boundaries": "maps/classic-2022/boundaries.geojson",
    "decisions": "maps/classic-2022/decisions.json",
    "directory": "maps/classic-2022/directory.json",
    "populations": "maps/classic-2022/populations.json"
  },
  "label": "2022 Yigions (Classic)",
  "links": {
    "boundaries": "https://example.com/api/maps/classic-2022/boundaries.geojson",
    "directory": "https://example.com/api/maps/classic-2022/directory.json",
    "metadata": "https://example.com/api/maps/classic-2022",
    "populations": "https://example.com/api/maps/classic-2022/populations.json"
  },
  "map_id": "classic-2022",
  "owner": null,
  "parameters": {
    "source": "handcrafted-2022",
    "target": 100000000
  },
  "published_at": "2022-01-01T00:00:00Z",
  "summary": {
    "n_clusters": 78,
    "total_pop": 7800000000
  },
  "visibility": "public"
}

GET /api/maps/<map_id>/boundaries.geojson API key ›

Return the cluster boundaries for a map as a GeoJSON FeatureCollection. Each feature has cluster_id, population, num_cells, and country codes in its properties.

Parameters

Name	In	Type	Description
map_id	path	string	Map identifier.

Sample response (200)

{
  "features": [
    {
      "geometry": {
        "coordinates": [
          [
            [
              -100.0,
              40.0
            ],
            [
              -99.0,
              40.0
            ],
            [
              -99.0,
              41.0
            ],
            [
              -100.0,
              40.0
            ]
          ]
        ],
        "type": "Polygon"
      },
      "properties": {
        "cluster_id": "AAA",
        "countries": [
          "US"
        ],
        "num_cells": 1,
        "population": 1234567
      },
      "type": "Feature"
    }
  ],
  "type": "FeatureCollection"
}

GET /api/maps/<map_id>/populations.json API key ›

Return per-cluster population totals plus the parameters used to generate the map.

Parameters

Name	In	Type	Description
map_id	path	string	Map identifier.

Sample response (200)

{
  "clusters": {
    "AAA": 1234567,
    "AAB": 1100000
  },
  "parameters": {
    "source": "handcrafted-2022",
    "target": 100000000
  }
}

GET /api/maps/<map_id>/directory.json API key ›

Return per-cluster directory entries with names, centroids, country lists, and target-fit percentage.

Parameters

Name	In	Type	Description
map_id	path	string	Map identifier.

Sample response (200)

{
  "AAA": {
    "centroid_lat": 40.5,
    "centroid_lng": -99.5,
    "cluster_id": "AAA",
    "countries": [
      "US"
    ],
    "name": "Example Cluster",
    "num_cells": 1,
    "num_countries": 1,
    "pct_of_target": 1.2,
    "population": 1234567
  }
}

GET /api/reference/countries.geojson API key ›

Return a simplified Natural Earth country reference layer used by the workbench canvas.

Sample response (200)

{
  "features": [
    {
      "geometry": {
        "coordinates": [],
        "type": "MultiPolygon"
      },
      "properties": {
        "iso_a3": "USA",
        "name": "United States"
      },
      "type": "Feature"
    }
  ],
  "type": "FeatureCollection"
}