API Reference

Overview

mapjson returns topojson (or geojson) for any geographic layer in a single API call. The shortest possible call returns Natural Earth 110m world countries with no attached properties — the most common use case for a world map.

// Minimal call — 110m world countries, no properties
d3.json("https://api.mapjson.com/v1/geo").then(topo => {
  const countries = topojson.feature(topo, topo.objects.geo);
  // draw your map
});

// With filtering and properties
d3.json("https://api.mapjson.com/v1/geo?layer=countries&filter=europe&detail=medium&properties=name,iso2")
  .then(topo => { /* ... */ });

Endpoint

Layers

Detail Levels

Properties

Only applies to the countries layer. No properties are returned by default — pass ?properties=name,iso2 to request specific fields, keeping the response as small as possible. Regions and districts include gid, name, parent_gid, and iso2 in every response automatically; passing properties has no effect on those layers.

currencies, languages, idd, and demonym return null for territories without an official ISO 3166-1 assignment (disputed territories, Antarctica, etc. — 249 of mapjson's 265 countries/territories have a match).

Examples

https://api.mapjson.com/v1/geo

https://api.mapjson.com/v1/geo?layer=countries&filter=europe&detail=medium&properties=name,iso2

https://api.mapjson.com/v1/geo?layer=regions&filter=FR&detail=high

https://api.mapjson.com/v1/geo?layer=regions&filter=US&detail=medium

https://api.mapjson.com/v1/geo?layer=regions&filter=PL&detail=high

https://api.mapjson.com/v1/geo?layer=lakes&detail=medium&format=geojson

https://api.mapjson.com/v1/points?type=city&filter=US-MA

Response

The default response is a topojson Topology object. The feature collection is always at topo.objects.geo regardless of which layer you requested. All responses include Access-Control-Allow-Origin: *.

{
  "type": "Topology",
  "objects": {
    "geo": {
      "type": "GeometryCollection",
      "geometries": [
        {
          "type": "Polygon",
          "arcs": [[0, 1, 2]],
          "properties": {
            "name": "France",
            "iso2": "FR",
            "iso3": "FRA",
            "isoNum": "250",
            "continent": "Europe",
            "capital": "Paris",
            "capitalLat": 48.8566,
            "capitalLng": 2.3515
          }
        }
        // ...
      ]
    }
  },
  "arcs": [ ... ]
}

When no properties parameter is given, each feature's properties object is empty ({}).

Format size comparison

Filtered topojson responses have unreferenced arcs pruned, making them significantly smaller than the equivalent geojson. Shared border arcs are deduplicated in topojson; geojson re-emits full floating-point coordinates for every feature independently.

Sizes are uncompressed. gzip compression narrows the gap somewhat; topojson still wins for all request types.

Identifiers

Every feature returned by the API has a stable gid property — a string key you can use to join map geometry to your own data. gid values are always present in the response, regardless of the properties parameter.

Hierarchy

Features below the country level carry a parent_gid property that links upward through the hierarchy. You can traverse the full tree without downloading extra geometry.

district  06037  (Los Angeles County)
  └─ region   US-CA  (California)
       └─ country  US  (United States)

The parent_gid of a region is always a country ISO alpha-2. The parent_gid of a district is always the state's ISO 3166-2.

Catalog endpoint

The catalog lists every gid in a layer with its name, parent, and all known external codes — useful for building lookup tables or crosswalks without downloading geometry.

GET /v1/catalog?layer=countries
GET /v1/catalog?layer=regions&filter=PL
GET /v1/catalog?layer=districts&filter=US
GET /v1/catalog?layer=districts&filter=US-MA

filter is required for regions, districts, and postal. Accepts the same values as /v1/geo: an ISO alpha-2 country code (US) or an ISO 3166-2 region code (US-MA) for districts. Omitting it returns an error. The countries layer ignores filter.

Returns a JSON array. Example entry for a region:

{
  "gid":        "US-CA",
  "name":       "California",
  "layer":      "regions",
  "parent_gid": "US",
  "iso2":       "US",
  "gid_source": "iso3166-2"
}

Country entries additionally carry minDetail — the lowest detail level whose geometry includes that country. Small nations that Natural Earth omits at 110m report "medium" or "high", so you can request the right detail up front instead of getting an empty response. Example country entry:

{
  "gid":        "CV",
  "name":       "Cabo Verde",
  "layer":      "countries",
  "parent_gid": null,
  "iso2":       "CV",
  "iso3":       "CPV",
  "isoNum":     "132",
  "continent":  "Africa",
  "subregion":  "Western Africa",
  "minDetail":  "medium"
}

Joining to external data

The gid is chosen to match codes your data already uses. Census, CDC, BLS, and most US federal sources use 5-digit FIPS for counties — join on gid directly. For countries, ISO alpha-2 is the most widely used identifier in web APIs and statistical databases. For states and international regions, ISO 3166-2 is used by Eurostat, NUTS crosswalks, and most administrative data sources. Where a dataset uses a different code system, use the catalog to build a translation table. Where it uses names rather than codes — Deutschland, Mass, Calif. — post them to /v1/resolve and get gids back.

Resolve

Your data rarely uses gid values. It uses names — Deutschland, Mass, Calif., Türkiye, a column of FIPS codes. /v1/resolve maps those keys to gids so you can join them to geometry. It is the only POST endpoint, because it takes a batch of keys as a JSON body.

Send Content-Type: application/json and a body with a keys array:

curl -X POST https://api.mapjson.com/v1/resolve \
  -H "Content-Type: application/json" \
  -d '{"keys": ["Mass", "Calif.", "N.Y."]}'

Context is a bias, not a filter: a contradicted hint lowers a candidate's score rather than removing it, so a stray country name in a column of US states still resolves — with a lower confidence. Beyond three keys the resolver also derives its own consensus from the keys that matched cleanly, which is why a batch of state names disambiguates itself without any context at all.

Response

{"keys": ["Mass", "Deutschland", "Xanadu"]}, abridged:

{
  "requestId":     "3379f2cd-…",
  "indexBuiltAt":  "2026-07-14T15:50:01.140Z",
  "consensus":     { "layer": "regions", "country": "US", "anchorCount": 3 },
  "counts":        { "resolved": 1, "low_confidence": 1, "miss": 1 },
  "results": [
    {
      "key":        "Mass",
      "status":     "resolved",
      "confidence": 0.99,
      "gid":        "US-MA",
      "name":       "Massachusetts",
      "layer":      "regions",
      "parent":     "US",
      "crosswalk":  { "fipsState": "25", "postal": "MA" },
      "explanation": {
        "normalized": "mass",
        "tier":       "exact_name",
        "matched":    "mass",
        "nameType":   "alias",
        "source":     "us-states.json",
        "factors":    ["consensus_layer_match", "consensus_country_match"]
      }
    },
    { "key": "Deutschland", "status": "low_confidence", "gid": "DE", "…": "…" },
    { "key": "Xanadu", "status": "miss", "confidence": 0, "…": "…" }
  ]
}

The gid on each result is the join key for /v1/geo — that is the whole point of the call. crosswalk carries the entity's other known codes (iso2, iso3, isoNum, fips, fipsState, postal, zcta), and explanation records why the match was made, so a bad resolution is auditable rather than mysterious.

counts tallies the statuses so you can check a batch without walking it. A malformed body — keys missing, empty, not an array, over 1000 entries, or an invalid context.layer — returns 400 with {"error": "…"}.

No key required, CORS enabled — call it straight from the browser. Clean is this endpoint with a UI: paste a column, see what resolved, download the gids. The renewable electricity example joins a real dataset by country name in one call.

Country Codes

Use these ISO alpha-2 codes with the filter parameter (e.g. filter=DE) to retrieve a specific country.

Points

Point datasets — places rather than boundaries — are served from a separate endpoint, always as GeoJSON (points have no shared geometry, so topojson and detail don't apply). Today the only type is city; more point types will follow.

Each feature carries name, countryIso2, countryName, continent, region (the admin-1 gid, always matching the regions layer: ISO 3166-2 where Natural Earth carries it, e.g. US-MA; Natural Earth's placeholder codes elsewhere, e.g. Kosovo's XK-X20; null only for Hargeysa — Natural Earth has no usable coding for Somaliland), popMetro, and capital (true for national capitals, false otherwise). popMetro is the metropolitan / urban-agglomeration population (e.g. Tokyo ≈ 35.7M for Greater Tokyo, not the ~9M city proper).

Sample response

GET /v1/points?type=city&filter=FR — a standard GeoJSON FeatureCollection of Point features:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [2.353, 48.8581] },
      "properties": {
        "name": "Paris",
        "nameLocal": null,
        "countryIso2": "FR",
        "countryName": "France",
        "continent": "Europe",
        "region": "FR-75",
        "popMetro": 9904000,
        "capital": true
      }
    }
    // ...
  ]
}

Every city carries capital — true for national capitals, false otherwise. coordinates are [longitude, latitude], per GeoJSON.

Sources

Every dataset mapjson serves is open and free to use. Attribution by area: