API Reference

Overview

mapjson returns topojson (or geojson) for any geographic layer in a single AJAX call. The shortest possible call returns 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.

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

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"
}

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.

Country Codes

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