> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to Mapbox

The Mapbox connector lets your AI agent act in each user's Mapbox account. Each user connects their own Mapbox API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 20 tools.

**Authentication:** API Key
**Categories:** Search, Productivity
**Tools:** 20: 20 read, 0 write, 0 destructive
**Users sign in with:** API key
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=MAPBOX)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Mapbox connection

   In **AgentKit > Connections**, create a Mapbox connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'mapbox'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Mapbox:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'mapbox_geocode_forward_structured',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "mapbox"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Mapbox:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="mapbox_geocode_forward_structured",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their Mapbox credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'mapbox_dataset_feature_get',
  toolInput: {
    dataset_id: '<dataset_id>',
    feature_id: '<feature_id>',
    username: '<username>',
  },
  connector: 'mapbox',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="mapbox_dataset_feature_get",
    tool_input={
        "dataset_id": "<dataset_id>",
        "feature_id": "<feature_id>",
        "username": "<username>",
    },
    connection_name="mapbox",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `mapbox_dataset_feature_get`

Get Dataset Feature · Read-only

Get one GeoJSON feature from a Mapbox dataset by its ID.
Returns the feature with id, geometry and properties.
Use mapbox_dataset_feature_get when you know the feature ID. Use mapbox_dataset_features_list to browse.
Needs a token with the datasets:read scope.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `dataset_id` (`string`, required): ID of the dataset, from mapbox_datasets_list. Example: cjvf1msb3060i2vp6bq9m7t6l.
- `feature_id` (`string`, required): ID of the feature, from mapbox_dataset_features_list. Example: f6d9.
- `username` (`string`, required): The Mapbox username of the account that owns the datasets, shown in the Mapbox console. Example: mapbox-user.

Example input: `{"dataset_id":"<dataset_id>","feature_id":"<feature_id>","username":"<username>"}`

### `mapbox_dataset_features_list`

List Dataset Features · Read-only

List the GeoJSON features stored in a Mapbox dataset.
Returns a GeoJSON FeatureCollection; each feature has id, geometry and properties.
Use mapbox_dataset_features_list to read a dataset's data. Use mapbox_dataset_feature_get for one feature by ID.
Needs a token with the datasets:read scope. To get the next page, pass the id of the last feature as start, and stop when no features come back.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `dataset_id` (`string`, required): ID of the dataset, from mapbox_datasets_list. Example: cjvf1msb3060i2vp6bq9m7t6l.
- `username` (`string`, required): The Mapbox username of the account that owns the datasets, shown in the Mapbox console. Example: mapbox-user.
- `limit` (`integer`, optional): Maximum number of features, from 1 to 1000. Defaults to 1000. Example: 100.
- `start` (`string`, optional): ID of the last feature on the previous page, to list the features after it. Example: f6d9.

Example input: `{"dataset_id":"<dataset_id>","username":"<username>"}`

### `mapbox_dataset_get`

Get Dataset · Read-only

Get the metadata of one Mapbox dataset.
Returns id, name, description, owner, created, modified, bounds, features (the count) and size in bytes.
Use mapbox_dataset_get to inspect one dataset. Use mapbox_dataset_features_list to read its features.
Needs a token with the datasets:read scope.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `dataset_id` (`string`, required): ID of the dataset, from mapbox_datasets_list. Example: cjvf1msb3060i2vp6bq9m7t6l.
- `username` (`string`, required): The Mapbox username of the account that owns the datasets, shown in the Mapbox console. Example: mapbox-user.

Example input: `{"dataset_id":"<dataset_id>","username":"<username>"}`

### `mapbox_datasets_list`

List Datasets · Read-only

List the datasets in a Mapbox account.
Returns an array of datasets, each with id, name, description, owner, created, modified, bounds, feature count and size.
Use mapbox_datasets_list to find a dataset_id. Use mapbox_dataset_get for one dataset and mapbox_dataset_features_list for its features.
Needs a token with the datasets:list scope. Mapbox can return fewer than limit before the end; to get the next page, pass the id of the last dataset as start, and stop when a page comes back empty.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `username` (`string`, required): The Mapbox username of the account that owns the datasets, shown in the Mapbox console. Example: mapbox-user.
- `limit` (`integer`, optional): Maximum number of datasets to return. Example: 20.
- `sortby` (`string`, optional): Sort order: modified (most recently changed first) or created (oldest first). Example: modified. One of: `modified`, `created`.
- `start` (`string`, optional): ID of the last dataset on the previous page, to list the datasets after it. Example: cjvf1msb3060i2vp6bq9m7t6l.

Example input: `{"username":"<username>"}`

### `mapbox_directions_get`

Get Directions · Read-only

Get a route between 2 to 25 points for driving, driving with traffic, walking or cycling from the Mapbox Directions API.
Returns routes, each with distance in meters, duration in seconds, geometry and legs (with turn-by-turn steps when steps is true), plus the snapped waypoints and a code such as Ok or NoRoute.
Use mapbox_directions_get to route through points in the given order. Use mapbox_optimized_trip_get to find the best visiting order, mapbox_matrix_get for travel times between many points, and mapbox_map_matching_get to snap a recorded GPS trace.
Get coordinates from mapbox_geocode_forward or mapbox_search_forward when you only have addresses.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `coordinates` (`string`, required): The points to route through, in order, as 2 to 25 longitude,latitude pairs separated by semicolons. Example: -122.42,37.78;-122.45,37.91.
- `profile` (`string`, required): Routing profile: driving-traffic (car, with live and historic traffic), driving (car), walking or cycling. Sent as mapbox/<profile>. Example: driving. One of: `driving-traffic`, `driving`, `walking`, `cycling`.
- `alternatives` (`boolean`, optional): Set true to also return up to two alternative routes when they exist. Defaults to false. Example: true.
- `annotations` (`string`, optional): Extra per-segment data to return, comma-separated: distance, duration, speed, congestion, congestion_numeric, maxspeed, closure. Needs overview set to full. Congestion and closure are only available for driving-traffic. Example: distance,duration.
- `approaches` (`string`, optional): Side of the road to arrive from at each waypoint, semicolon-separated: unrestricted (default) or curb. Give one value per waypoint; leave a position empty to skip it. The first value is not used, so start the list with a semicolon. Example: ;curb.
- `arrive_by` (`string`, optional): Desired arrival time, in the same ISO 8601 formats as depart_at. Only for the driving profile. Example: 2026-12-01T09:00.
- `bearings` (`string`, optional): Direction of travel at each coordinate, semicolon-separated, each as angle,deviation in degrees clockwise from true north (deviation 45 or 90 is typical). Leave a position empty to skip it. Example: 60,45;;45,45.
- `continue_straight` (`boolean`, optional): Set true to keep going in the same direction after an intermediate waypoint, or false to allow a U-turn. Defaults to true for driving and false for walking and cycling. Example: false.
- `depart_at` (`string`, optional): Departure time, in ISO 8601 format YYYY-MM-DDThh:mm:ssZ, YYYY-MM-DDThh:mm:ss±hh:mm or YYYY-MM-DDThh:mm (local time at the first coordinate). Only for driving and driving-traffic. Do not combine with arrive_by. Example: 2026-12-01T08:30.
- `exclude` (`string`, optional): Road types to avoid, comma-separated: motorway, toll, ferry, unpaved, cash_only_tolls, tunnel, country_border, state_border (most only for driving and driving-traffic). Avoidance is best effort. Example: toll,ferry.
- `geometries` (`string`, optional): Format of returned route geometry: geojson (a GeoJSON LineString), polyline (precision 5, the default) or polyline6 (precision 6). Use geojson to read coordinates directly. Example: geojson. One of: `geojson`, `polyline`, `polyline6`.
- `language` (`string`, optional): Language of turn-by-turn instruction text, such as en, de or es. Defaults to en. Only used with steps set to true. Example: de.
- `max_height` (`number`, optional): Vehicle height in meters, 0 to 10, to avoid roads with lower limits. Driving profiles only. Example: 3.5.
- `max_weight` (`number`, optional): Vehicle weight in metric tons, 0 to 100, to avoid roads with lower limits. Driving profiles only. Example: 7.5.
- `max_width` (`number`, optional): Vehicle width in meters, 0 to 10, to avoid narrower roads. Driving profiles only. Example: 2.5.
- `overview` (`string`, optional): Detail of the overview geometry: full, simplified (the default) or false for none. Example: full. One of: `full`, `simplified`, `false`.
- `radiuses` (`string`, optional): Maximum distance in meters each coordinate may move to snap to the road network, one value per coordinate separated by semicolons; leave a position empty to use the default. Values: any number greater than 0 or unlimited. Example: 50;;100.
- `steps` (`boolean`, optional): Set true to return turn-by-turn steps and instructions. Defaults to false. Example: true.
- `waypoint_names` (`string`, optional): Names for the waypoints, semicolon-separated, used in arrival instructions; the first is the origin. Up to 500 characters in total. Only used with steps set to true. Example: Home;Work.
- `waypoints` (`string`, optional): Zero-based indexes of the coordinates to treat as waypoints (start and end of legs), semicolon-separated. Must include 0 and the last index. Other coordinates only shape the path. Example: 0;2.

Example input: `{"coordinates":"<coordinates>","profile":"driving-traffic"}`

### `mapbox_geocode_batch`

Batch Geocode · Read-only

Run many forward, structured and reverse geocoding queries in one Mapbox Geocoding v6 request.
Returns batch, an array with one GeoJSON FeatureCollection per query in the order sent; a query with no match has an empty features array.
Use mapbox_geocode_batch for a list of addresses or coordinates. Use mapbox_geocode_forward or mapbox_geocode_reverse for a single lookup.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `queries` (`array`, required): The geocoding queries to run, in order. Each item is one forward query (q plus optional filters such as types, country, bbox, proximity or limit), one structured query (address_number, street, place, region, postcode, country and so on) or one reverse query (longitude and latitude). Filters with several values can be arrays or comma-separated strings. Mapbox documents up to 1000 queries per request, but its error table also names a 50-query limit, so send 50 or fewer per call. Each query is billed as one Geocoding request. Example: [{"q": "1600 Pennsylvania Avenue NW, Washington, DC 20500", "types": ["address"], "limit": 1}, {"longitude": -73.986136, "latitude": 40.748895, "types": ["address"]}].
- `permanent` (`boolean`, optional): Set true when you intend to store the results (permanent geocoding). Permanent geocoding needs a credit card on file or an enterprise contract on the Mapbox account and is billed at a different rate. Defaults to false (temporary results that must not be cached). Example: false.

Example input: `{"queries":[]}`

### `mapbox_geocode_forward`

Geocode Address · Read-only

Convert an address or place name in free text into coordinates with Mapbox Geocoding v6.
Returns a GeoJSON FeatureCollection; each feature has the coordinates, full_address, feature_type, match_code and the context (street, place, region, postcode, country).
Use mapbox_geocode_forward for one free-text address. Use mapbox_geocode_forward_structured when the address is already split into parts, mapbox_geocode_batch for many addresses, and mapbox_search_forward to find businesses and points of interest, which Geocoding v6 does not return.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `q` (`string`, required): The address or place to look up, such as a full address, a city or a postcode. At most 256 characters and 20 words, with no semicolon. Example: 2 Lincoln Memorial Circle SW, Washington, DC.
- `autocomplete` (`boolean`, optional): Set false to return only exact matches instead of results that start with the query (true is the default). Use false for complete addresses. Example: false.
- `bbox` (`string`, optional): Limit results to a bounding box, as four comma-separated numbers in minLon,minLat,maxLon,maxLat order. The box cannot cross the 180th meridian. Example: -74.27,40.49,-73.68,40.92.
- `country` (`string`, optional): Limit results to one or more countries, as comma-separated ISO 3166 alpha-2 codes. Example: us,ca.
- `language` (`string`, optional): Language of the returned text, as an IETF language tag. List several, comma-separated, to get translations; the first is the primary language. Example: en.
- `limit` (`integer`, optional): Maximum number of results, from 1 to 10. Defaults to 5. Example: 3.
- `permanent` (`boolean`, optional): Set true when you intend to store the results (permanent geocoding). Permanent geocoding needs a credit card on file or an enterprise contract on the Mapbox account and is billed at a different rate. Defaults to false (temporary results that must not be cached). Example: false.
- `proximity` (`string`, optional): Bias results toward a location, as longitude,latitude, or the string ip to bias by the caller's IP address. Example: -73.99,40.73.
- `types` (`string`, optional): Return only these feature types, comma-separated. Options: country, region, postcode, district, place, locality, neighborhood, street and address. Example: address,street.
- `worldview` (`string`, optional): Return boundaries and names as seen by a regional audience. Defaults to us. Example: in. One of: `ar`, `cn`, `in`, `jp`, `ma`, `rs`, `ru`, `tr`, `us`.

Example input: `{"q":"<q>"}`

### `mapbox_geocode_forward_structured`

Geocode Structured Address · Read-only

Convert an address that is already split into parts (house number, street, city, region, postcode, country) into coordinates with Mapbox Geocoding v6.
Returns a GeoJSON FeatureCollection; each feature has the coordinates, full_address, feature_type, match_code and context.
Use mapbox_geocode_forward_structured when you have address fields from a form or database; give at least one address part. Use mapbox_geocode_forward for a single free-text address.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `address_line1` (`string`, optional): House number and street in one line. Use this or address_number and street. Example: 1600 Pennsylvania Ave NW.
- `address_number` (`string`, optional): House number on its own, used with street. Example: 1600.
- `autocomplete` (`boolean`, optional): Set false to return only exact matches; Mapbox recommends false for structured input. Defaults to true. Example: false.
- `bbox` (`string`, optional): Limit results to a bounding box, as four comma-separated numbers in minLon,minLat,maxLon,maxLat order. The box cannot cross the 180th meridian. Example: -74.27,40.49,-73.68,40.92.
- `block` (`string`, optional): Block, an address component in some countries such as Japan. Example: 1丁目.
- `country` (`string`, optional): Country as an ISO 3166 alpha-2 code, which strictly filters results, or a full country name, which only biases them. Example: us.
- `language` (`string`, optional): Language of the returned text, as an IETF language tag. List several, comma-separated, to get translations; the first is the primary language. Example: en.
- `limit` (`integer`, optional): Maximum number of results, from 1 to 10. Defaults to 5. Example: 1.
- `locality` (`string`, optional): Official sub-city area used in postal addresses in some countries, such as an arrondissement in France. Example: 7e Arrondissement.
- `neighborhood` (`string`, optional): Neighborhood name. Example: Foggy Bottom.
- `permanent` (`boolean`, optional): Set true when you intend to store the results (permanent geocoding). Permanent geocoding needs a credit card on file or an enterprise contract on the Mapbox account and is billed at a different rate. Defaults to false (temporary results that must not be cached). Example: false.
- `place` (`string`, optional): City, town or village. Example: Washington.
- `postcode` (`string`, optional): Postal code. Example: 20500.
- `proximity` (`string`, optional): Bias results toward a location, as longitude,latitude, or the string ip to bias by the caller's IP address. Example: -73.99,40.73.
- `region` (`string`, optional): State, province or other top-level region. Example: DC.
- `street` (`string`, optional): Street name on its own, used with address_number. Example: Pennsylvania Ave NW.
- `types` (`string`, optional): Return only these feature types, comma-separated. Options: country, region, postcode, district, place, locality, neighborhood, street and address. Example: address,street.
- `worldview` (`string`, optional): Return boundaries and names as seen by a regional audience. Defaults to us. Example: in. One of: `ar`, `cn`, `in`, `jp`, `ma`, `rs`, `ru`, `tr`, `us`.

Example input: `{}`

### `mapbox_geocode_reverse`

Reverse Geocode · Read-only

Look up the address and places at a longitude and latitude with Mapbox Geocoding v6.
Returns a GeoJSON FeatureCollection of the address, street, neighborhood, place, region, postcode and country at that point, each with full_address and context.
Use mapbox_geocode_reverse to turn coordinates into an address. Use mapbox_search_reverse to also get points of interest near the point.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `latitude` (`number`, required): Latitude of the location to look up, in decimal degrees between -90 and 90. Example: 40.733.
- `longitude` (`number`, required): Longitude of the location to look up, in decimal degrees between -180 and 180. Example: -73.989.
- `country` (`string`, optional): Limit results to one or more countries, as comma-separated ISO 3166 alpha-2 codes. Example: us,ca.
- `language` (`string`, optional): Language of the returned text, as an IETF language tag. List several, comma-separated, to get translations; the first is the primary language. Example: en.
- `limit` (`integer`, optional): Maximum number of results, from 1 to 5. Defaults to 1 per level (one address, one place, one region and so on). A value above 1 requires exactly one value in types. Example: 3.
- `permanent` (`boolean`, optional): Set true when you intend to store the results (permanent geocoding). Permanent geocoding needs a credit card on file or an enterprise contract on the Mapbox account and is billed at a different rate. Defaults to false (temporary results that must not be cached). Example: false.
- `types` (`string`, optional): Return only these feature types, comma-separated. Options: country, region, postcode, district, place, locality, neighborhood, street and address. Example: address,street.
- `worldview` (`string`, optional): Return boundaries and names as seen by a regional audience. Defaults to us. Example: in. One of: `ar`, `cn`, `in`, `jp`, `ma`, `rs`, `ru`, `tr`, `us`.

Example input: `{"latitude":40.733,"longitude":-73.989}`

### `mapbox_isochrone_get`

Get Isochrone · Read-only

Calculate the area reachable from a point within given travel times or distances with the Mapbox Isochrone API.
Returns a GeoJSON FeatureCollection with one contour per requested time or distance, as lines or polygons, with contour value and color properties.
Use mapbox_isochrone_get to answer what can be reached within N minutes or meters. Use mapbox_matrix_get for travel times to specific points.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `coordinates` (`string`, required): The center point, as one longitude,latitude pair. Example: -118.22258,33.99038.
- `profile` (`string`, required): Routing profile: driving-traffic (car, with live and historic traffic), driving (car), walking or cycling. Sent as mapbox/<profile>. Example: driving. One of: `driving-traffic`, `driving`, `walking`, `cycling`.
- `contours_colors` (`string`, optional): Hex colors without # for each contour, comma-separated, one per contour. Example: 6706ce,04e813,4286f4.
- `contours_meters` (`string`, optional): Travel distances in meters for up to four contours, comma-separated in increasing order, each at most 100000. Provide this or contours_minutes. Example: 1000,2000.
- `contours_minutes` (`string`, optional): Travel times in minutes for up to four contours, comma-separated in increasing order, each at most 60. Provide this or contours_meters. Example: 5,10,15.
- `denoise` (`number`, optional): From 0.0 to 1.0: drops contours smaller than this fraction of the largest one. Defaults to 1.0, which keeps only the largest. Example: 0.5.
- `depart_at` (`string`, optional): Departure time, in ISO 8601 format YYYY-MM-DDThh:mm:ssZ, YYYY-MM-DDThh:mm:ss±hh:mm or YYYY-MM-DDThh:mm (local time at the first coordinate). Defaults to now. Contours reflect traffic at that time. Example: 2026-12-01T08:30.
- `exclude` (`string`, optional): Road types to avoid, comma-separated: motorway, toll, ferry, unpaved, cash_only_tolls (driving and driving-traffic only). Avoidance is best effort. Example: toll,ferry.
- `generalize` (`number`, optional): Simplification tolerance in meters for the contour shapes. Example: 50.
- `polygons` (`boolean`, optional): Set true to return contours as polygons instead of lines (false is the default). Example: true.

Example input: `{"coordinates":"<coordinates>","profile":"driving-traffic"}`

### `mapbox_map_matching_get`

Match GPS Trace · Read-only

Snap a recorded GPS trace to the road and path network with the Mapbox Map Matching API.
Returns matchings, each with confidence (0 to 1), distance, duration, geometry and legs, plus tracepoints that map each input point to the network (null for dropped points).
Use mapbox_map_matching_get to clean up a recorded trip or measure the distance actually driven. Use mapbox_directions_get to plan a new route.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `coordinates` (`string`, required): The recorded trace, as 2 to 100 longitude,latitude pairs separated by semicolons, in the order recorded. Example: -117.17282,32.71204;-117.17288,32.71225;-117.17293,32.71244.
- `profile` (`string`, required): Routing profile: driving-traffic (car, with live and historic traffic), driving (car), walking or cycling. Sent as mapbox/<profile>. Example: driving. One of: `driving-traffic`, `driving`, `walking`, `cycling`.
- `annotations` (`string`, optional): Extra per-segment data to return, comma-separated: distance, duration, speed, congestion, congestion_numeric, maxspeed. Needs overview set to full. Example: distance,duration.
- `approaches` (`string`, optional): Side of the road to arrive from at each waypoint, semicolon-separated: unrestricted (default) or curb. Give one value per waypoint; leave a position empty to skip it. Needs steps set to true. Example: ;curb.
- `depart_at` (`string`, optional): Departure time, in ISO 8601 format YYYY-MM-DDThh:mm:ssZ, YYYY-MM-DDThh:mm:ss±hh:mm or YYYY-MM-DDThh:mm (local time at the first coordinate). Defaults to now. Example: 2026-12-01T08:30.
- `geometries` (`string`, optional): Format of returned route geometry: geojson (a GeoJSON LineString), polyline (precision 5, the default) or polyline6 (precision 6). Use geojson to read coordinates directly. Example: geojson. One of: `geojson`, `polyline`, `polyline6`.
- `ignore` (`string`, optional): Routing restrictions to ignore, comma-separated: access, oneways, restrictions. Driving profile only. Example: oneways.
- `language` (`string`, optional): Language of turn-by-turn instruction text, such as en, de or es. Defaults to en. Only used with steps set to true. Example: de.
- `overview` (`string`, optional): Detail of the overview geometry: full, simplified (the default) or false for none. Example: full. One of: `full`, `simplified`, `false`.
- `radiuses` (`string`, optional): Maximum distance in meters each coordinate may move to snap to the road network, one value per coordinate separated by semicolons; leave a position empty to use the default. Values: 0 to 50, default 5; use 20 to 50 for noisy GPS. Example: 50;;100.
- `steps` (`boolean`, optional): Set true to return turn-by-turn steps and instructions. Defaults to false. Example: true.
- `tidy` (`boolean`, optional): Set true to remove clusters and resample the trace before matching. Defaults to false. Example: true.
- `timestamps` (`string`, optional): Unix timestamps in seconds, one per coordinate, semicolon-separated and ascending. Strongly improves matching. Example: 1700000000;1700000005;1700000010.
- `waypoint_names` (`string`, optional): Names for the waypoints, semicolon-separated, used in arrival instructions; the first is the origin. Up to 500 characters in total. Only used with steps set to true. Example: Home;Work.
- `waypoints` (`string`, optional): Zero-based indexes of the coordinates to treat as waypoints (start and end of legs), semicolon-separated. Must include 0 and the last index. Other coordinates only shape the path. Example: 0;2.

Example input: `{"coordinates":"<coordinates>","profile":"driving-traffic"}`

### `mapbox_matrix_get`

Get Travel Time Matrix · Read-only

Calculate travel times and distances between many origins and destinations at once with the Mapbox Matrix API.
Returns durations (seconds) and, when requested, distances (meters) as arrays indexed [source][destination], plus the snapped sources and destinations; unreachable pairs are null.
Use mapbox_matrix_get to compare or rank many trips, such as finding the nearest of several stores. Use mapbox_directions_get for the route geometry and steps of one trip.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `coordinates` (`string`, required): The points, as 2 to 25 longitude,latitude pairs separated by semicolons (at most 10 for driving-traffic). Example: -122.42,37.78;-122.45,37.91;-122.48,37.73.
- `profile` (`string`, required): Routing profile: driving-traffic (car, with live and historic traffic), driving (car), walking or cycling. Sent as mapbox/<profile>. Example: driving. One of: `driving-traffic`, `driving`, `walking`, `cycling`.
- `annotations` (`string`, optional): Which matrices to return: duration (the default), distance, or duration,distance for both. Example: duration,distance. One of: `duration`, `distance`, `duration,distance`, `distance,duration`.
- `approaches` (`string`, optional): Side of the road to arrive from at each waypoint, semicolon-separated: unrestricted (default) or curb. Give one value per waypoint; leave a position empty to skip it. Example: ;curb.
- `bearings` (`string`, optional): Direction of travel at each coordinate, semicolon-separated, each as angle,deviation in degrees clockwise from true north (deviation 45 or 90 is typical). Leave a position empty to skip it. Example: 60,45;;45,45.
- `depart_at` (`string`, optional): Departure time, in ISO 8601 format YYYY-MM-DDThh:mm:ssZ, YYYY-MM-DDThh:mm:ss±hh:mm or YYYY-MM-DDThh:mm (local time at the first coordinate). It cannot be in the past, and Mapbox enables it per account on request. Example: 2026-12-01T08:30.
- `destinations` (`string`, optional): Zero-based indexes of the coordinates to use as destinations, semicolon-separated, or all (the default). Example: 1;2.
- `fallback_speed` (`number`, optional): Speed in km/h used to estimate a straight-line value when no route exists between two points, instead of returning null. Example: 30.
- `sources` (`string`, optional): Zero-based indexes of the coordinates to use as origins, semicolon-separated, or all (the default). Example: 0.

Example input: `{"coordinates":"<coordinates>","profile":"driving-traffic"}`

### `mapbox_optimized_trip_get`

Optimize Trip · Read-only

Find the fastest order to visit 2 to 12 stops with the Mapbox Optimization API v1, a traveling-salesman solver.
Returns trips (distance, duration, geometry and legs of the optimized route) and waypoints, each with waypoint_index giving its position in the optimized order.
Use mapbox_optimized_trip_get when the visiting order is free, for example a delivery round. Use mapbox_directions_get when the order is fixed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `coordinates` (`string`, required): The stops to visit, as 2 to 12 longitude,latitude pairs separated by semicolons. The first is the start and, by default, the end of the trip. Example: 13.388860,52.517037;13.397634,52.529407;13.428555,52.523219.
- `profile` (`string`, required): Routing profile: driving-traffic (car, with live and historic traffic), driving (car), walking or cycling. Sent as mapbox/<profile>. Example: driving. One of: `driving-traffic`, `driving`, `walking`, `cycling`.
- `annotations` (`string`, optional): Extra per-segment data to return, comma-separated: duration, distance, speed. Needs overview set to full. Example: distance,duration.
- `approaches` (`string`, optional): Side of the road to arrive from at each waypoint, semicolon-separated: unrestricted (default) or curb. Give one value per waypoint; leave a position empty to skip it. Needs steps set to true. Example: ;curb.
- `bearings` (`string`, optional): Direction of travel at each coordinate, semicolon-separated, each as angle,deviation in degrees clockwise from true north (deviation 45 or 90 is typical). Leave a position empty to skip it. Needs radiuses. Example: 60,45;;45,45.
- `destination` (`string`, optional): Where the trip ends: any (the default) or last. Example: last. One of: `any`, `last`.
- `distributions` (`string`, optional): Pick-up and drop-off pairs, semicolon-separated, each as pickupIndex,dropoffIndex of the coordinates; each pick-up is visited before its drop-off. The first coordinate cannot be a drop-off. Example: 3,1.
- `geometries` (`string`, optional): Format of returned route geometry: geojson (a GeoJSON LineString), polyline (precision 5, the default) or polyline6 (precision 6). Use geojson to read coordinates directly. Example: geojson. One of: `geojson`, `polyline`, `polyline6`.
- `language` (`string`, optional): Language of turn-by-turn instruction text, such as en, de or es. Defaults to en. Only used with steps set to true. Example: de.
- `overview` (`string`, optional): Detail of the overview geometry: full, simplified (the default) or false for none. Example: full. One of: `full`, `simplified`, `false`.
- `radiuses` (`string`, optional): Maximum distance in meters each coordinate may move to snap to the road network, one value per coordinate separated by semicolons; leave a position empty to use the default. Values: any number greater than 0 or unlimited. Example: 50;;100.
- `roundtrip` (`boolean`, optional): Set false for a one-way trip; then source must be first and destination last. Defaults to true (return to the start). Example: false.
- `source` (`string`, optional): Where the trip starts: any (the default) or first. Example: first. One of: `any`, `first`.
- `steps` (`boolean`, optional): Set true to return turn-by-turn steps and instructions. Defaults to false. Example: true.

Example input: `{"coordinates":"<coordinates>","profile":"driving-traffic"}`

### `mapbox_search_categories_list`

List Categories · Read-only

List every point-of-interest category the Mapbox Search Box API supports.
Returns listItems, each with canonical_id, name, icon and version, in the requested language.
Use mapbox_search_categories_list to find the category_id for mapbox_search_category or the IDs for poi_category filters.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `language` (`string`, optional): ISO 639-1 language code for the returned names. Defaults to en. Example: fr.

Example input: `{}`

### `mapbox_search_category`

Search by Category · Read-only

List points of interest in one category, such as coffee, gas_station or hotel, near a location with the Mapbox Search Box API.
Returns a GeoJSON FeatureCollection of up to 25 places, each with coordinates, name, full_address, poi_category, distance and metadata.
Use mapbox_search_category to browse a category around a point or inside a bbox. Use mapbox_search_forward to search by name.
Get valid category IDs from mapbox_search_categories_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category_id` (`string`, required): Canonical ID of the category to search, from mapbox_search_categories_list. Example: coffee.
- `bbox` (`string`, optional): Limit results to a bounding box, as four comma-separated numbers in minLon,minLat,maxLon,maxLat order. The box cannot cross the 180th meridian. Example: -74.27,40.49,-73.68,40.92.
- `country` (`string`, optional): Limit results to one or more countries, as comma-separated ISO 3166 alpha-2 codes. Example: us,ca.
- `eta_type` (`string`, optional): Set to navigation to add an estimated travel time (eta, in minutes) to each result. Also needs navigation_profile and origin or proximity. Each ETA is billed as a Matrix API element. Example: navigation. One of: `navigation`.
- `language` (`string`, optional): ISO 639-1 language code for the returned names. Defaults to en. Example: fr.
- `limit` (`integer`, optional): Maximum number of results, from 1 to 25. Example: 5.
- `navigation_profile` (`string`, optional): Travel mode for ETA calculation when eta_type is navigation. Example: driving. One of: `driving`, `walking`, `cycling`.
- `near` (`string`, optional): Bias results toward a place described in free text (a city or area name) or a longitude,latitude pair. When Mapbox resolves it, near overrides proximity. Names of single landmarks or points of interest are ignored. Example: Brooklyn, NY.
- `origin` (`string`, optional): Starting point for distance and ETA calculation, as longitude,latitude. Example: -73.99,40.73.
- `poi_category_exclusions` (`string`, optional): Leave out points of interest in these canonical category IDs, comma-separated. Get IDs from mapbox_search_categories_list. Example: fast_food.
- `proximity` (`string`, optional): Bias results toward a location, as longitude,latitude, or the string ip to bias by the caller's IP address. Defaults to ip. Example: -73.99,40.73.

Example input: `{"category_id":"<category_id>"}`

### `mapbox_search_forward`

Search Places · Read-only

Search for addresses, places and points of interest by text with the Mapbox Search Box API, in one request.
Returns a GeoJSON FeatureCollection; each feature has coordinates, name, full_address, feature_type, poi_category, context and metadata such as phone and website.
Use mapbox_search_forward to find businesses or places by name with coordinates in one call. Use mapbox_search_category to list every place of one category near a point, and mapbox_geocode_forward for street addresses only.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `q` (`string`, required): What to search for, such as an address, a place, a business name or a type of place, up to 256 characters. Example: Blue Bottle Coffee.
- `auto_complete` (`boolean`, optional): Set true to include partial and fuzzy matches. Example: true.
- `bbox` (`string`, optional): Limit results to a bounding box, as four comma-separated numbers in minLon,minLat,maxLon,maxLat order. The box cannot cross the 180th meridian. Example: -74.27,40.49,-73.68,40.92.
- `country` (`string`, optional): Limit results to one or more countries, as comma-separated ISO 3166 alpha-2 codes. Example: us,ca.
- `eta_type` (`string`, optional): Set to navigation to add an estimated travel time (eta, in minutes) to each result. Also needs navigation_profile and origin or proximity. Each ETA is billed as a Matrix API element. Example: navigation. One of: `navigation`.
- `language` (`string`, optional): ISO 639-1 language code for the returned names. Defaults to en. Example: fr.
- `limit` (`integer`, optional): Maximum number of results, from 1 to 10. Example: 5.
- `minimum_rating` (`number`, optional): Return only places with an average rating at least this high, from 0.0 to 5.0, where ratings are known. Example: 4.
- `navigation_profile` (`string`, optional): Travel mode for ETA calculation when eta_type is navigation. Example: driving. One of: `driving`, `walking`, `cycling`.
- `near` (`string`, optional): Bias results toward a place described in free text (a city or area name) or a longitude,latitude pair. When Mapbox resolves it, near overrides proximity. Names of single landmarks or points of interest are ignored. Example: Brooklyn, NY.
- `open_now` (`boolean`, optional): Set true to return only points of interest open now, where hours are known. Example: true.
- `origin` (`string`, optional): Starting point for distance and ETA calculation, as longitude,latitude. Example: -73.99,40.73.
- `poi_category` (`string`, optional): Return only points of interest in these canonical category IDs, comma-separated. Get IDs from mapbox_search_categories_list. Example: coffee,restaurant.
- `poi_category_exclusions` (`string`, optional): Leave out points of interest in these canonical category IDs, comma-separated. Get IDs from mapbox_search_categories_list. Example: fast_food.
- `proximity` (`string`, optional): Bias results toward a location, as longitude,latitude, or the string ip to bias by the caller's IP address. Defaults to ip. Example: -73.99,40.73.
- `types` (`string`, optional): Return only these feature types, comma-separated. Options: country, region, postcode, district, place, city, locality, neighborhood, block, street, address, poi and category. Example: poi,address.

Example input: `{"q":"<q>"}`

### `mapbox_search_retrieve`

Retrieve Suggested Place · Read-only

Get the full details of one suggestion returned by mapbox_search_suggest.
Returns a GeoJSON FeatureCollection with the feature's coordinates, name, full_address, context, poi_category, maki icon and metadata such as phone, website and opening hours.
Use mapbox_search_retrieve after mapbox_search_suggest, with the same session_token, to end the search session.
Requires a mapbox_id from mapbox_search_suggest.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `mapbox_id` (`string`, required): The mapbox_id of the suggestion to retrieve, from a mapbox_search_suggest result. Example: dXJuOm1ieHBvaTo0ZTg2ZWFkNS1jOWMwLTQ3OWEtOTA5Mi1kMDVlNDQ3NDdlODk.
- `session_token` (`string`, required): Your own ID that groups one interactive search for billing, ideally a UUIDv4 you generate. Use the same value for the mapbox_search_suggest calls and the mapbox_search_retrieve call of one search, and a new value for each new search. It must match the session_token of the preceding suggest calls. Example: 0f5bd5a3-3b6e-4c3e-9f2a-5b6c7d8e9f01.
- `attribute_sets` (`string`, optional): Extra metadata to add, comma-separated: photos, visit (hours, rating, price level) and venue. The basic set is always included. Example: photos,visit.
- `language` (`string`, optional): ISO 639-1 language code for the returned names. Defaults to en. Example: fr.
- `proximity` (`string`, optional): A longitude,latitude to measure the returned distance from. Example: -83.748708,42.265837.

Example input: `{"mapbox_id":"<mapbox_id>","session_token":"<session_token>"}`

### `mapbox_search_reverse`

Reverse Search · Read-only

Find the addresses and points of interest at or around a longitude and latitude with the Mapbox Search Box API.
Returns a GeoJSON FeatureCollection of nearby features, each with coordinates, name, full_address, feature_type and context.
Use mapbox_search_reverse to learn what businesses or places are at a point. Use mapbox_geocode_reverse to get only the address hierarchy.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `latitude` (`number`, required): Latitude of the location to look up, in decimal degrees between -90 and 90. Example: 40.733.
- `longitude` (`number`, required): Longitude of the location to look up, in decimal degrees between -180 and 180. Example: -73.989.
- `country` (`string`, optional): Limit results to one or more countries, as comma-separated ISO 3166 alpha-2 codes. Example: us,ca.
- `language` (`string`, optional): ISO 639-1 language code for the returned names. Defaults to en. Example: fr.
- `limit` (`integer`, optional): Maximum number of results, from 1 to 10. Example: 5.
- `types` (`string`, optional): Return only these feature types, comma-separated. Options: country, region, prefecture, postcode, district, place, city, locality, oaza, block, street, address, poi and category. Example: poi,address.

Example input: `{"latitude":40.733,"longitude":-73.989}`

### `mapbox_search_suggest`

Suggest Places · Read-only

Get type-ahead suggestions for addresses, places, points of interest, brands and categories from the Mapbox Search Box API.
Returns suggestions, each with name, mapbox_id, feature_type, full_address or place_formatted, poi_category and distance, but no coordinates.
Use mapbox_search_suggest for interactive autocomplete, then pass the chosen mapbox_id with the same session_token to mapbox_search_retrieve for coordinates. Use mapbox_search_forward for a one-off search that returns coordinates directly.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `q` (`string`, required): The partial or complete text the user typed, up to 256 characters. Example: Michigan Stadium.
- `session_token` (`string`, required): Your own ID that groups one interactive search for billing, ideally a UUIDv4 you generate. Use the same value for the mapbox_search_suggest calls and the mapbox_search_retrieve call of one search, and a new value for each new search. Example: 0f5bd5a3-3b6e-4c3e-9f2a-5b6c7d8e9f01.
- `bbox` (`string`, optional): Limit results to a bounding box, as four comma-separated numbers in minLon,minLat,maxLon,maxLat order. The box cannot cross the 180th meridian. Example: -74.27,40.49,-73.68,40.92.
- `country` (`string`, optional): Limit results to one or more countries, as comma-separated ISO 3166 alpha-2 codes. Example: us,ca.
- `eta_type` (`string`, optional): Set to navigation to add an estimated travel time (eta, in minutes) to each result. Also needs navigation_profile and origin or proximity. Each ETA is billed as a Matrix API element. Example: navigation. One of: `navigation`.
- `language` (`string`, optional): ISO 639-1 language code for the returned names. Defaults to en. Example: fr.
- `limit` (`integer`, optional): Maximum number of results, from 1 to 10. Example: 5.
- `navigation_profile` (`string`, optional): Travel mode for ETA calculation when eta_type is navigation. Example: driving. One of: `driving`, `walking`, `cycling`.
- `near` (`string`, optional): Bias results toward a place described in free text (a city or area name) or a longitude,latitude pair. When Mapbox resolves it, near overrides proximity. Names of single landmarks or points of interest are ignored. Example: Brooklyn, NY.
- `origin` (`string`, optional): Starting point for distance and ETA calculation, as longitude,latitude. Example: -73.99,40.73.
- `poi_category` (`string`, optional): Return only points of interest in these canonical category IDs, comma-separated. Get IDs from mapbox_search_categories_list. Example: coffee,restaurant.
- `poi_category_exclusions` (`string`, optional): Leave out points of interest in these canonical category IDs, comma-separated. Get IDs from mapbox_search_categories_list. Example: fast_food.
- `proximity` (`string`, optional): Bias results toward a location, as longitude,latitude, or the string ip to bias by the caller's IP address. Defaults to ip. Example: -73.99,40.73.
- `types` (`string`, optional): Return only these feature types, comma-separated. Options: country, region, postcode, district, place, city, locality, neighborhood, block, street, address, poi and category. Example: poi,address.

Example input: `{"q":"<q>","session_token":"<session_token>"}`

### `mapbox_tilequery_get`

Query Tileset Features · Read-only

Get the features of one or more Mapbox vector or rasterarray tilesets at or near a point with the Tilequery API.
Returns a GeoJSON FeatureCollection, closest first; each feature has its properties, the closest point as geometry and tilequery metadata (distance, geometry type, layer).
Use mapbox_tilequery_get to read map data at a location, such as the building, land use or elevation contour there, or features from your own tileset. Use mapbox_search_reverse for addresses and businesses.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `latitude` (`number`, required): Latitude of the point to query, in decimal degrees between -90 and 90. Example: 40.733.
- `longitude` (`number`, required): Longitude of the point to query, in decimal degrees between -180 and 180. Example: -73.989.
- `tileset_id` (`string`, required): ID of the tileset to query, or up to 25 comma-separated IDs. Mapbox tilesets include mapbox.mapbox-streets-v8 and mapbox.mapbox-terrain-v2; your own tilesets are username.tileset. Example: mapbox.mapbox-streets-v8.
- `bands` (`string`, optional): For rasterarray tilesets, the bands to query, comma-separated. Example: 1708304400.
- `dedupe` (`boolean`, optional): Set false to keep duplicate features. Defaults to true. Example: false.
- `geometry` (`string`, optional): Return only one geometry type: polygon, linestring or point. Example: point. One of: `polygon`, `linestring`, `point`.
- `layers` (`string`, optional): Layers to query, comma-separated, instead of all layers. Required in practice for rasterarray tilesets. Example: poi_label,building.
- `limit` (`integer`, optional): Maximum number of features, from 1 to 50, closest first. Defaults to 5. Example: 10.
- `radius` (`number`, optional): Search distance in meters. Defaults to 0, a point-in-polygon query that returns only polygons containing the point; set a radius to find points and lines. Example: 30.

Example input: `{"latitude":40.733,"longitude":-73.989,"tileset_id":"<tileset_id>"}`

## Related

Other Search connectors ([all 89](/agentkit/connectors/?category=search)):

- [Supadata](/agentkit/connectors/supadata/): Scalekit connector, API key, 21 tools
- [Exa](/agentkit/connectors/exa/): Scalekit connector, API key, 21 tools
- [Brave Search](/agentkit/connectors/brave/): Scalekit connector, API key, 18 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
