canonical: https://jentic.com/apis/nextbillion.ai/nextbillion-ai

# NextBillion.ai Mapping API

NextBillion.ai provides mapping and navigation APIs for directions, distance matrix calculations, geocoding, snap-to-roads functionality, and isochrone analysis. The API supports multiple transport modes including car, truck, bike, and foot routing with advanced truck routing options. Rate limits vary by endpoint, with geocoding at 2400 queries per minute and snap-to-roads at 6000 queries per minute.

## For AI agents

Calculate routes between waypoints, geocode addresses, snap GPS coordinates to roads, compute distance matrices, and generate isochrone maps for reachability analysis across multiple transport modes.

## Scope

Does not handle map tile rendering, real-time traffic updates, or place search with business details - use for routing, geocoding, and distance calculations only.

## Capabilities

- Calculate route directions between up to 200 waypoints with support for car, truck, bike, and foot modes
- Compute distance and duration matrices between multiple origin and destination sets
- Geocode addresses to coordinates and reverse geocode coordinates to addresses
- Snap GPS coordinate traces to road networks with timestamp support
- Generate isochrone maps showing reachable areas within time or distance constraints
- Configure truck routing with flexible options for vehicle restrictions and avoidances
- Calculate travel times and distances with support for avoiding highways, tolls, and ferries

## Use cases

### Last-Mile Delivery Routing

Optimize delivery routes for logistics operations with support for up to 200 waypoints per request using the POST method. The Directions API handles multi-stop routes with configurable transport modes, avoidances for highways or tolls, and alternative route suggestions. Truck routing mode supports vehicle-specific restrictions and flexible routing parameters for commercial fleet operations.

Example prompt: Calculate an optimized route for a delivery van visiting 5 customer locations, avoiding highways and returning to the warehouse depot

### Fleet Travel Time Analysis

Calculate travel times and distances between fleet locations and customer sites using the Distance Matrix API. The API processes multiple origins and destinations in a single request, returning duration and distance for each origin-destination pair. Supports car and truck modes with flexible routing options for commercial vehicles.

Example prompt: Compute the travel time and distance from 3 warehouse locations to 10 customer sites to determine the optimal warehouse assignment

### Address Geocoding and Validation

Convert customer addresses to geographic coordinates for mapping and routing applications with the Geocoding API. The forward geocoding endpoint accepts place names, addresses, or localities and returns position data with optional country filtering and proximity bias. Reverse geocoding converts coordinates back to human-readable addresses at a rate of 2400 queries per minute.

Example prompt: Geocode a customer delivery address to coordinates, verify the location accuracy, and then reverse geocode the coordinates to get the formatted address

### GPS Trace Map Matching

Clean and align GPS tracking data from vehicle fleets by snapping coordinate traces to the actual road network. The Snap to Roads API processes up to 200 points per request via POST method, supporting custom search radiuses and timestamp data for each point. Returns the snapped coordinates along with the matched road geometry in GeoJSON or polyline format.

Example prompt: Snap a vehicle's GPS trace of 50 coordinate points to the road network and return the aligned path with matched road geometry

### AI Agent Route Planning Through Jentic

Enable AI agents to calculate routes and geocode addresses through Jentic's unified API catalog without managing NextBillion.ai API keys directly. Agents search for routing operations by intent, load the endpoint schema, and execute requests with credential isolation. The integration eliminates the need for API key distribution and enables semantic search across 10,000+ APIs.

Example prompt: Search for 'calculate route between locations' in Jentic, load the NextBillion.ai Directions endpoint schema, and execute a route calculation request with origin and destination coordinates

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/directions/json` | Calculate route directions between waypoints |
| POST | `/directions/json` | Calculate directions for up to 200 waypoints |
| GET | `/distancematrix/json` | Calculate distance matrix between origins and destinations |
| GET | `/geocode` | Convert address to geographic coordinates |
| GET | `/revgeocode` | Convert coordinates to human-readable address |
| GET | `/snapToRoads/json` | Snap GPS coordinates to nearest roads |
| GET | `/isochrone/json` | Calculate reachable area within time or distance limits |

## Key resources

- **Routes** — Turn-by-turn directions between waypoints
- **Distance Matrix** — Travel time and distance calculations
- **Geocodes** — Address to coordinate conversions
- **Snapped Points** — GPS coordinates aligned to roads
- **Isochrones** — Reachable area polygons by time or distance

## Why Jentic

- **Setup:** Wiring the NextBillion.ai Mapping API by hand means attaching your API key to every request to api.nextbillion.io and assembling routing, geocoding, and distance-matrix queries from raw parameters. Through Jentic you install once, import the NextBillion.ai Mapping API from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** Requests to this API carry their coordinates and addresses in query parameters and bodies rather than a resource id in the path, so scope your agent to the operations it needs, such as directions and geocoding, while leaving distance-matrix or isochrone calls out of the allowed set unless you add them.
- **Credential handling:** Your NextBillion.ai API key is stored once, encrypted, by your own Jentic One instance and attached to each request at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'calculate a route' or 'geocode an address' and Jentic returns the matching NextBillion.ai operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HERE Maps API** — HERE provides similar routing and geocoding capabilities with additional traffic data and map rendering features
- **TomTom Routing API** — TomTom offers routing and traffic APIs with extensive global coverage and real-time traffic updates
- **MapQuest API** — MapQuest provides routing, geocoding, and mapping services with generous free tier limits
- **Geocodio** — Geocodio specializes in North American address geocoding with data appends for congressional districts and census data
- **LocationIQ** — LocationIQ offers geocoding and mapping built on OpenStreetMap data with competitive pricing

## FAQ

### What authentication does the NextBillion.ai Mapping API use?

The NextBillion.ai Mapping API uses API key authentication passed as a query parameter named 'key'. When using this API through Jentic, API keys are stored encrypted in your Jentic One instance and agents receive scoped access tokens, so raw keys never enter the agent's context.

### Can I calculate routes with multiple waypoints using the NextBillion.ai API?

Yes. The GET endpoint supports up to 50 waypoints, while the POST endpoint at `/directions/json` supports up to 200 waypoints. Both methods support car, truck, bike, and foot transport modes with optional avoidances for highways, tolls, and ferries.

### What are the rate limits for the NextBillion.ai Mapping API?

Rate limits vary by endpoint. The Geocoding and Reverse Geocoding endpoints support 2400 queries per minute. The Snap to Roads and Isochrone endpoints support 6000 queries per minute. The Directions and Distance Matrix endpoints have standard limits documented at docs.nextbillion.ai.

### How do I geocode addresses with the NextBillion.ai API through Jentic?

Search Jentic for 'geocode an address', load the NextBillion.ai forward geocoding endpoint schema (GET /geocode), and execute with your address in the 'q' parameter. The API returns position coordinates, address components, and map view bounds. Install Jentic with 'pip install jentic' and authenticate through Jentic One, the self-hosted execution layer.

### Does the NextBillion.ai API support truck routing?

Yes. Set the 'mode' parameter to 'truck' and use 'option=flexible' to enable advanced truck routing features with vehicle-specific restrictions. The flexible option is available for both Directions and Distance Matrix endpoints when using truck mode.

### What is an isochrone and how do I generate one with NextBillion.ai?

An isochrone is a polygon showing the area reachable from a starting point within a given time or distance. Use the GET `/isochrone/json` endpoint with your starting coordinates, transport mode, and either 'contours_minutes' for time-based limits or 'contours_meters' for distance-based limits. The API returns a GeoJSON FeatureCollection with up to 4 isochrone polygons per request.

### How does the Snap to Roads API handle GPS tracking data?

The Snap to Roads API accepts a pipe-separated string of coordinate points via the 'path' parameter. The GET method supports fewer than 100 points, while the POST method supports up to 200 points. You can optionally provide radiuses for search distance per point and timestamps for temporal matching. The API returns snapped coordinates with the matched road geometry.

### Can I limit what my agent is allowed to do with the NextBillion.ai Mapping API?

Yes. Because you run Jentic One yourself, your own rules decide which NextBillion.ai operations the agent may call and which credentials it may use. Since requests to this API carry their coordinates and addresses in query parameters and bodies rather than a resource id in the path, you scope the agent to just the operations it needs, such as directions and geocoding, and leave distance-matrix or isochrone calls out of the allowed set unless you add them. The stored API key is attached only at execution time for the operations you have permitted, so the agent never gains broader access than you grant.