Tour Maps for agents

Make, check and publish a Tour Map from an agent. Seven tools, three permissions, and a server that places every stop.

An agent with the Bazantic connector can make a Tour Map for a person. The agent sends the settings, the stops and a theme. The server places each stop, checks the theme and saves a private draft. The person approves the draft. Then the agent publishes it.

Tools

The connector lists seven tools. Each tool needs one permission.

Tool	Permission	What it does
`bazantic_tour_list`	`tour:read`	Lists your Tour Maps with their status, version and links.
`bazantic_tour_get`	`tour:read`	Reads one draft: the stops, the follow-ups, the theme check, the art and the missing release requirements.
`bazantic_tour_prepare`	`tour:write`	Creates a private draft from settings, stops and a theme. Places the stops.
`bazantic_tour_update`	`tour:write`	Changes the settings, the stops, the theme or the top five. Confirms a pin.
`bazantic_tour_art_allocate`	`tour:write`	Reserves an image upload for the `hero` slot or the `card` slot.
`bazantic_tour_art_confirm`	`tour:write`	Checks the uploaded image and sets it as the art of the slot.
`bazantic_tour_publish`	`tour:publish`	Publishes the draft after the person approves it.

No tool publishes a tour except bazantic_tour_publish. It needs confirm: true. A call without confirm: true fails.

Permissions

The connector asks for three permissions when you connect it.

Permission	What it allows
`tour:read`	Read your Tour Map drafts and their preview links.
`tour:write`	Create and change your Tour Map drafts and upload their art.
`tour:publish`	Publish Tour Maps after your approval.

The session names the account and the person. No tool takes an account or a user as input. An agent cannot read the drafts of another person.

Your role in the account also counts. An owner or an operator can change drafts. A viewer can only read them. Only an owner can publish. A published tour uses the account as its sponsor, and only an owner approves spend for the account. A session without a permission does not list the tools for that permission.

Reconnect an older connector

A connector that you connected before Tour Maps shipped has no tour permissions. A token refresh keeps the permissions of the first grant. Disconnect the connector. Then connect it again and approve the three permissions.

Make a tour

Collect the area, the travel mode and the stops from the person. Give each stop a name, an address, a source link, a category, a blurb and a visit time.
Choose a theme. A theme is a set of tokens. The tokens name the colors, the map colors, two fonts, a pin icon, the corner style and the map base.
Call bazantic_tour_prepare with an idempotency_key. The server places the stops and saves a private draft.
Read the view. Each stop has a state: placed, confirm or unplaced. The missing list names what the release still needs.
Fix each open follow-up with bazantic_tour_update. Send the current version with each call.
Add art if the person wants it. See Add art.
Give the preview_url to the person. Ask the person to approve the draft in the chat.
Call bazantic_tour_publish with confirm: true. The result holds the public_url.

The server checks the contrast of the theme colors. If a color pair fails, the call returns invalid_tour_theme and names the failed pair.

The server places every stop

No tool input has a coordinate field. A stop with a latitude or a longitude fails the schema check. The server finds the place of each stop with the Geoapify geocoder. Each call places at most 16 stops. A placement uses no credit of your account.

A stop can match more than one place. The view then shows the state confirm and at most three candidates. Call bazantic_tour_update with a confirm item. Send the stop_id and the candidate_id. The stop becomes placed.

The server cannot place some stops. These stops have the state unplaced. Correct the address with bazantic_tour_update. Only a new stop or a changed address calls the geocoder.

An open confirm follow-up or blocking follow-up stops the release. The publish call returns release_blocked and names the stop.

Add art

A tour has two art slots. The hero slot is 16:9. The card slot is 1:1.

Call bazantic_tour_art_allocate with the slot, the content_type and the byte_size. The type is JPEG, PNG or WebP. The size is at most 8 MiB.
Send the bytes with a PUT to the returned url. Use the returned headers. Send them before expires_at.
Call bazantic_tour_art_confirm with the upload_id. The server checks the image and sets the slot.

The confirm call changes the draft. Use the new version for the next write. The call fails if the image has the wrong type, size or shape for its slot. An upload that you do not confirm within 15 minutes is deleted.

Versions and retries

Each draft has a version. Each write needs the current version. If the draft changed, the call fails with version_conflict. Read the draft again, then retry.

bazantic_tour_prepare and bazantic_tour_publish take an idempotency_key. A retry with the same key returns the first result. The same key with other input fails with idempotency_conflict. A publish key belongs to one version. To publish an edit, use a new key.

Limits

The server places each stop at no cost to you. Each person can place 240 stops and allocate 30 art uploads in one hour. A call over a limit fails with unavailable. The message gives the wait in seconds.

Errors

A failed call returns an error with a short message. The code is in error.data.code.

Code	Meaning	What to do
`invalid_request`	The input fails the schema.	Correct the input. Do not send coordinates.
`unauthorized`	The session is not valid.	Connect the connector again.
`insufficient_scope`	The session lacks the permission.	Reconnect and approve the permission.
`forbidden`	Your role in the account does not allow the call.	Ask an owner. Only an owner can publish.
`not_found`	The account has no draft with this id.	Call `bazantic_tour_list`.
`version_conflict`	The draft changed after you read it.	Read the draft. Retry with its `version`.
`idempotency_conflict`	The key belongs to a request with other input.	Use a new key for new input.
`release_blocked`	A release check fails. The message names the stop.	Close the follow-up. Publish again.
`invalid_tour_theme`	A color pair fails the contrast check. The message names the pair.	Change the colors.
`tour_too_large`	The draft exceeds the size limit.	Remove stops or shorten the text.
`unavailable`	The tour service did not answer, or a limit applies.	Retry after the wait in the message, or after a short delay.

Tour Maps for agents

On this page