Mapbox
Add browser maps, geocoding, directions, and static maps to a Swarmz project
Connect Mapbox when a project needs an interactive map, place search, reverse geocoding, routing, or a static map image. The connection can hold a public token, a secret token, or both.
Mapbox uses a shared project connection. Requests count against the connected Mapbox account and its token restrictions.
Availability
A Swarmz administrator must show Mapbox under Platform config > Integrations. Mapbox does not require a Swarmz OAuth application.
Before you connect
- Add a public token beginning
pk.when browser code needs Mapbox GL JS. Restrict it to the generated app's allowed URLs and required public scopes. - Add a secret token beginning
sk.for server operations when you do not want to reuse the public token. Give it only the scopes the selected APIs need.
At least one token is required. When both are present, server operations prefer the secret token and public_token returns only the public token. Mapbox documents token scopes and URL restrictions.
Connect Mapbox
- In the Swarmz project, open Settings > Integrations and select Mapbox.
- Select Add connection.
- Paste a public token, a secret token, or both.
- Select Save connection. Swarmz tests each supplied token with a bounded geocoding request.
Secret tokens stay behind the connector gateway. A public token can be returned only through the explicit public_token operation for browser-map setup.
Available operations
| Operation | What it does | Limit per minute |
|---|---|---|
public_token | Returns the configured pk. token for browser Mapbox GL JS | 10 |
forward_geocode | Finds coordinates and place context for one search string | 30 |
reverse_geocode | Finds place context for one longitude and latitude | 30 |
directions | Calculates one route across 2 to 25 coordinate pairs | 20 |
static_map | Returns one bounded static map image as base64 | 10 |
Directions support driving, driving with traffic, walking, and cycling profiles. Static maps accept bounded dimensions and zoom; store the returned image when the app needs a durable asset.
Ask the AI to use Mapbox
- “Add a Mapbox map with markers for these locations and fit the viewport to the results.”
- “Build address search with forward geocoding and save the selected coordinates.”
- “Show a walking route between these points with distance and duration.”
- “Generate a static map preview for each property card without exposing a secret token.”
The AI requests the connection before wiring live Mapbox data. Browser maps use only the public token; geocoding, directions, and static maps run through generated server code and the connector gateway.
Verify Mapbox
- If a public token is configured, render a browser map on an allowed origin.
- Forward geocode a known address and compare its coordinates.
- Reverse geocode those coordinates and compare the returned place.
- Calculate a short test route and confirm its profile.
- Generate one static map and display the returned image.
Troubleshoot and recover
If a browser map is blank, inspect the public token's allowed URLs and scopes. If server operations return a permission error, add the required API scope or replace the server token. A valid token can still be blocked by its restrictions.
To rotate tokens, replace the affected field in the Swarmz connection and rerun the matching verification step before revoking the previous token. To disconnect, select Remove in Swarmz and revoke both tokens in Mapbox.