---
title: "Navigate the map"
method: POST
path: "/v1/tools/navigate"
---

# Navigate the map

`POST /v1/tools/navigate`

## Request

- Base URL: `https://api.ploti.ai`
- URL: `https://api.ploti.ai/v1/tools/navigate`
- Auth: HTTP bearer

Move the session's viewport — where you are looking and how close. Data availability follows the view: wide views expose more regional layers, close views unlock parcel-level data, and every query is scoped to the current viewport. Navigate as often as you need; each call replaces the view. Pass either a place name or a latitude/longitude center, never both. Every response reports the resulting zoom, the span in km, and whether parcels are queryable — read it and navigate again if the framing is wrong, rather than guessing a zoom up front.

## Request body

- object
  - `sessionId` string, required: The id start_session returned. Lost it? get_session without an id lists this workspace's open sessions.
  - `place` string: An address, city, county or state the geocoder resolves, e.g. 'Winter Garden, FL'. The viewport frames the place's extent unless zoom is given.
  - `latitude` number: Latitude of the viewport's center in WGS84 decimal degrees (north positive), e.g. from tools.location.geocode() or a row's coordinates. Pass with longitude. The place to look at, never the user's own location.
  - `longitude` number: Longitude of the viewport's center in WGS84 decimal degrees (east positive, so negative across the US). Pass with latitude.
  - `zoom` number: How close to look, as a web-map zoom level: 3 country, 8 region (up to ~140 km across), 10 metro (up to ~35 km, the widest view where parcels are queryable), 13 city (~4 km), 15 neighborhood (~1 km), 17 block (~250 m); values between presets sit between their spans, and actual views are often narrower. With a place, centers on it at this zoom instead of framing its extent; with coordinates, 13 when left out.

## Response `200`

What the tool returned: its text, any images, and structured data.

- object
  - `text` string, required
  - `images` object[], required
    - `mimeType` string
    - `data` string, byte
  - `data` unknown

## Other responses

- `400`: invalid_input: the arguments do not fit the tool's input schema.
- `403`: insufficient_scope: the credential may not use this tool.
- `404`: not_found: there is no such tool.
- `413`: payload_too_large: the body is over 256 KB (2 MB for /v1/tools).
- `415`: unsupported_media_type: a body was sent without Content-Type: application/json.
- `422`: tool_error: the tool refused or failed; error.message says why.
- `429`: rate_limited: this credential is over its rate. Retry after the Retry-After header's seconds.
- `500`: internal: Ploti failed. Retry; if it keeps happening, contact support.

---

[API](https://skmtc.dev/ploti/apis/ploti-api.md) · [All operations](https://skmtc.dev/ploti/apis/ploti-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ploti/apis/ploti-api/revisions/8c2c91c72d52?raw)