Getting started

TopoExport offers three HTTP APIs. They share one account, one plan and one dashboard.

Get a key

1. Sign in to the TopoExport app and open Services & API.
2. Start the API Trial or choose the API plan.
3. Create a tpk_ key in the Maps and geocoding tab for tiles and geocoding. The secret sk_ key of the Export API is in the Export API tab.

Authentication

Map tiles and geocoding

Pass the key in the key query parameter:

curl "https://geocode.topoexport.com/v1/geocode/search?text=Lyon&key=$TOPOEXPORT_API_KEY"

Each key has a list of allowed origins, set in the dashboard. A request is accepted when its Origin header, or else its Referer, starts with one of them. A key with no origin listed accepts every origin: use one for servers, scripts, QGIS and ArcGIS Pro, which send neither header.

Changes to a key (revocation, origins) apply everywhere within 60 seconds.

Export API

Send the secret key as a bearer token:

curl -H "Authorization: Bearer $TOPOEXPORT_SECRET_KEY" \
  "https://data.topoexport.com/lookup?lat=48.8584&lon=2.2945"

Plans and credits

Map tiles and geocoding draw on one pool of map credits. The Export API counts export credits separately. Prices are on the API page.

Map credits per request, for map tiles:

and for geocoding:

Export credits depend on the area and the format: see Export API credits.

• Only successful responses are billed. A response in error costs nothing.
• A geocoding response served from cache costs the same credits as a fresh one.
• On the API Trial, credits are granted once for 30 days. On the API plan they renew on the first day of each month (UTC). Beyond them, usage is billed up to the monthly spending cap you set for each product in the dashboard.
• All the keys of an account share the same credits.

Rate limits

Rate limits are there to stop abuse and keep the service responsive for every customer. We don't publish fixed figures: normal use of a web or mobile application, busy hours included, stays well below them. They apply as follows:

• Per key, for every request.
• Per key and per user IP for requests sent from a browser (with an Origin or Referer): a single user or script sending too many requests is slowed down without affecting the other users of your application.
• Lower from a local development server (Origin on localhost or 127.0.0.1).
• Server-side calls (no Origin) are only limited per key, since they all come from the same IP.

How the API answers:

Wait for Retry-After before retrying. If you plan a high request rate, a batch job or a launch, write to [email protected] beforehand and we will plan capacity with you.

Fair use

Storing the results your application uses is fine, for example the coordinates of an address a user saved. Without a written agreement, the following are not allowed:

• giving third parties access to the APIs through your own proxy or service;
• bulk downloading tiles or geocoding results;
• systematically caching tiles or geocoding results to build your own copy of the data.

Keys used this way may be rate-limited or deactivated.

Attribution

On the API Trial and API plans, display the data attribution on your map or next to your results:

• for maps, keep the map library's attribution control: the style and the TileJSON carry the sources to credit (OpenStreetMap contributors, cadastre publishers…);
• for geocoding results, show the geocoding.attribution string of the response;
• and add © TopoExport.

Errors

Map tiles and geocoding answer errors as JSON {"error": "…"}:

The Export API uses its own codes, listed in Export API errors.

Service status: status.topoexport.com.