TopoExport logo
Developer docs

Export API

Find the best official dataset for a location, then download its features over a bounding box as GeoJSON, glTF, OBJ, GeoTIFF or PNG.

Host: https://data.topoexport.com. The interactive reference of every endpoint and schema is served at the same address: data.topoexport.com.

Authentication

Send your secret key as a bearer token, from your server only:

curl -H "Authorization: Bearer $TOPOEXPORT_SECRET_KEY" "https://data.topoexport.com/usage"

The secret key is in the Export API tab of Services & API in the TopoExport app, where you can also regenerate it.

Workflow

An export takes two requests: find the datasets that cover a place, then download one of them over a bounding box.

1. Find datasets for a location

GET /lookup?lat={lat}&lon={lon}
GET /lookup?bbox={min_lon},{min_lat},{max_lon},{max_lat}

The response gives the deepest region containing the point (or the center of the bounding box) and the best datasets available there, one per type. Abridged:

{
  "region": {
    "id": "…",
    "isoCode": "FR-METRO",
    "name": "Metropolitan France",
    "localName": "France métropolitaine"
  },
  "datasets": [
    {
      "id": "…",
      "type": "BUILDINGS_3D",
      "minYear": 2024,
      "maxYear": 2025,
      "precision": 2,
      "srids": [2154],
      "lookupSrid": 2154,
      "regionIsoCode": "FR-METRO",
      "product": {
        "name": "BD TOPO",
        "licence": "CC BY 4.0",
        "publisher": { "name": "Institut national de l'information géographique et forestière", "shortName": "IGN" }
      }
    }
  ]
}
  • type: BUILDINGS_2D, BUILDINGS_3D, PARCELS, ROADS, RAILWAYS, WATERWAYS, GREEN_AREAS, TREES, HEDGES, CANOPY, RASTER_DTM (terrain), RASTER_DSM (surface), among others.
  • precision: the level of detail for BUILDINGS_3D, the grid resolution for RASTER_DTM.
  • lookupSrid: the coordinate reference system (EPSG code) best suited to this location. Pass it as targetSrid in step 2.
  • product: the source of the data, its publisher and its licence. Credit them as the licence requires.

2. Download features

GET /datasets/{id}/features?bbox={min_lon},{min_lat},{max_lon},{max_lat}&targetSrid={epsg}&format={format}
curl -H "Authorization: Bearer $TOPOEXPORT_SECRET_KEY" \
  -o buildings.geojson \
  "https://data.topoexport.com/datasets/$DATASET_ID/features?bbox=2.341735,48.852743,2.351291,48.857090&targetSrid=2154&format=geojson"

The response body is the file itself, with the Content-Type of its format.

ParameterRequiredMeaning
bboxyesmin_lon,min_lat,max_lon,max_lat in WGS 84 degrees. At most 100 km² per request
targetSridyesEPSG code of the output coordinates, usually the lookupSrid of step 1
formatyesgeojson, glb, obj, tiff or png, depending on the dataset type (see Formats)
resolutionnoGrid resolution of raster output, in metres. Defaults to the dataset's resolution
lodnoLevel of detail of 3D buildings: 1 or 2
terrainDatasetIdnoA RASTER_DTM dataset id: 3D output is placed on this terrain
buildingDefaultHeightnoHeight in metres given to buildings without one. Default 6
treeDefaultHeightnoHeight in metres given to trees without one. Default 6
geolocatenotrue (default): coordinates in targetSrid. false: coordinates relative to the south-west corner of the bounding box
outlinesnoRoads only: true returns road surfaces instead of centrelines. Default false
stepContournoTerrain in glb only: returns contour lines at this interval, in metres

Complete example

Find the 3D buildings dataset that covers an area, then download it as glTF in the coordinate system suited to that location. A location with no 3D buildings dataset gets a clear message instead of an error.

BBOX="2.341735,48.852743,2.351291,48.857090"
AUTH="Authorization: Bearer $TOPOEXPORT_SECRET_KEY"

# 1. datasets covering the bounding box (jq picks the 3D buildings)
read -r DATASET_ID SRID < <(
  curl -sf -H "$AUTH" "https://data.topoexport.com/lookup?bbox=$BBOX" |
    jq -r '.datasets[] | select(.type == "BUILDINGS_3D") | "\(.id) \(.lookupSrid)"' | head -n 1
)
[ -n "$DATASET_ID" ] || { echo "No 3D buildings dataset here"; exit 1; }

# 2. features of that dataset over the same bounding box
curl -sf -H "$AUTH" -o buildings.glb \
  "https://data.topoexport.com/datasets/$DATASET_ID/features?bbox=$BBOX&targetSrid=$SRID&format=glb&lod=2"

The secret key must stay on your server: call the Export API from a backend or a script, never from a web page.

Formats

Dataset typegeojsonglbobjtiffpng
BUILDINGS_2D✓
BUILDINGS_3D✓✓✓
PARCELS, RAILWAYS✓
ROADS, WATERWAYS, GREEN_AREAS, TREES, HEDGES, CANOPY✓✓
RASTER_DTM✓✓✓
RASTER_DSM✓✓

Media types: application/geo+json, model/gltf-binary, model/obj, image/tiff, image/png. Another combination answers 400.

Other endpoints

EndpointReturns
GET /datasets/{id}One dataset, same fields as in /lookup
GET /regions/lookup?lat=&lon=The region containing a point
GET /regions/{id}One region
GET /products/{id}One product (name, licence, publisher)
GET /publishers/{id}One publisher
GET /usageclientId, maxCredits and usedCredits of your key for the current period

Credits

An export request costs, in export credits:

hectares of the bounding box (rounded up) × 2 for glb × the dataset's multiplier
  • One credit is one hectare of one layer: 1 km² of buildings in GeoJSON costs 100 credits, the same area in glb costs 200.
  • The multiplier is 1 for most datasets; some, such as AI-detected trees, count double.
  • Only successful responses are billed.
  • usedCredits in /usage can lag a few minutes behind your actual consumption.
API TrialAPIEnterprise
Map credits (tiles + geocoding)2,000,000 for the trial5,000,000 per monthCustom
Beyond the map creditsRequests refused (429)€3, $3 or £3 per 1,000,000 credits, up to your capCustom
Export API credits4,000 for the trial4,000 per monthCustom
Beyond the export creditsRequests refused (403)€0.003, $0.003 or £0.003 per credit, up to your capCustom
API keys110Custom
Commercial useNoYesYes
Attribution requiredYesYesNo

On the API plan, credits beyond the included ones are billed up to the monthly spending cap you set in the Export API tab. When the cap is reached, or the trial credits are used up, export requests answer 403 until the next period.

Errors

StatusMeaning
400Invalid parameter: bounding box over 100 km² or malformed, format not available for this dataset, lod other than 1 or 2, stepContour not positive
401Missing or invalid key
403Export credits used up for the period
404Unknown dataset, region, product or publisher, or no region at this location