Carpathian Maps: A Map and Directions API

Carpathian Maps is a map and directions API that keeps your users' trips to itself. You put a world map on your website or app, and your backend asks for walk, bike, drive or transit directions, travel times and the area reachable from a point. All of it comes from Carpathian's own map server, built on open map data, so no third-party map provider receives a request carrying where your users are or where they're headed.

You enable it from Services, create an app for each website or service that uses it, and get a key for that app. Requests are free up to a monthly allowance and billed per thousand after that. The rest of this piece covers why a directions request is sensitive, how the map and the API connect, how keys and websites are protected, what it costs, and what it doesn't cover.

Why is a directions request sensitive?

A directions request carries two locations: where someone is and where they're going. Ask a hosted directions provider for a route and that provider receives both, along with the time, the mode of travel and whatever identifies your app. Repeat that across every trip your users plan and the provider holds a detailed record of their movements, kept under its own policies rather than yours.

Map tiles leak less but still leak. Every time a map loads or pans, the browser fetches the pieces of the map it's looking at, so the tile server learns which neighborhoods your users browse.

Carpathian Maps answers both from servers Carpathian runs. The coordinates in a route request stay on the map server and are never written to a log; the server records the time, the status and which app asked, nothing more. Carpathian's own platform sees only how many requests each app made each day, for the usage page and the bill.

What can you build with it?

The map and the directions work separately, so you can use either or both.

• A map on your site. The map is drawn in the browser with MapLibre GL JS from public map files, styled with the open Protomaps basemap, with labels in English and the OpenStreetMap credit in the corner.
• Directions. Send two points and a mode, and get back the distance, the time, the path to draw and step-by-step instructions. Transit answers name the bus line and departure times.
• Travel-time areas. Send one point and up to four travel times, and get back the area someone can reach in each. Useful for "within 15 minutes of you" searches and delivery zones.

The map covers the whole planet. Walk, bike and drive directions work wherever the map server's road coverage reaches, and the coverage table on the documentation's overview page lists it. The road data is the full OpenStreetMap planet, about 95 GB as OpenStreetMap publishes it, refreshed every month.

How do you put the map on your site?

You point a MapLibre map at the map server's files and give it the basemap style. The Connect guide has the whole example; the important part is the address your map reads from:

const base = "https://maps.carpathian.ai/map";

Before the map will load in a browser, list your website on your app in Carpathian, for example https://app.example.com. A browser on any website that isn't listed is refused, so another site can't embed your map and run up your usage. Add every address the map appears on, including a http://localhost address if you develop locally.

Keep the OpenStreetMap credit visible. The data's license requires it, and the example in the guide already shows it.

How does your backend ask for directions?

Your backend sends a POST with the app's key as a bearer token:

curl https://maps.carpathian.ai/v1/route \
  -H "Authorization: Bearer $MAPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin":{"lat":41.5868,"lng":-93.625},"destination":{"lat":41.6005,"lng":-93.6091},"mode":"walk"}'

The answer has the route's time in seconds, its distance in meters, the path as latitude and longitude pairs, and one step per instruction. The API reference lists every field and every error. Your browser or mobile app asks your backend, and your backend asks Carpathian Maps, so the key never leaves your servers.

How are keys and websites protected?

Each app gets its own key, which starts with cmk_. It's shown once, when you create the app, and Carpathian keeps only a hash of it. The map server never holds the key either: it receives the list of hashes and checks each request against it.

• Rotate or delete, and the old key stops working within a minute. The map server fetches the list of keys every minute, and a rotated or deleted key isn't on the next one.
• No shared secret between Carpathian and the map server. Each signs what it sends with its own key and checks the other's signature against a public key it holds. Someone who could tamper with the connection couldn't add a key to the list, and an old list can't be replayed to bring a revoked key back.
• Limits per app. Each app has a limit of requests a minute and a day, which you set. A request over either is refused with a 429 and a time to retry, so a bug that loops on your side can't run up a bill.
• Two-factor authentication is required to rotate a key or delete an app, and the three permissions (view, manage, delete) can be granted to team members separately.

What does it cost?

Each organization gets a free monthly allowance of route and travel-time requests. Past it, requests are billed per thousand on your monthly invoice, at the rate shown on the Carpathian Maps service page. Map file requests aren't billed, and requests the server can't answer because something on its side failed don't count. The Maps page shows this month's requests against the allowance as they happen, and a spend cap on your organization pauses your apps' keys when it's reached instead of letting usage run past it.

What doesn't it cover?

Transit covers the bus systems listed in the coverage table, which today is DART in the Des Moines metro. A transit request anywhere else answers that no route was found. Transit grows one region at a time, because each region's timetables are built into their own graph.

There's no address search. Carpathian Maps turns coordinates into routes and areas, so if your users type addresses, you'll need a geocoder to turn those into latitude and longitude first.

The map's labels are in English, and the styles are the Protomaps basemap's own: light, dark, white, grayscale and black. If your design needs something further from those, you can restyle the map in your own MapLibre code, but that style is yours to maintain.

Where Carpathian fits

Carpathian Maps is for teams that want maps and directions in their product without handing their users' movements to a map provider, and who are comfortable calling an API from their own backend. It answers coordinates, not addresses, and its transit coverage is regional. If your app needs worldwide transit or address search today, you'll still want a provider that offers those.

If it fits, create an account or sign in, enable Carpathian Maps from Services, and follow the Connect guide. The usage policy covers the limits and pricing in full.