Connect your systems to Metamaps

Use the Integration API to retrieve and update spots, images, events, and current congestion values from external systems. Call the API from your server. To display a map on a website, use Web Embed; for a mobile app, use the SDK.

Get an API key

In the Metamaps admin console, open Advanced settings → Integration API key for your map. Check the key and its permissions, then send it in the X-Api-Key header of every request.

X-Api-Key: pmk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

You can configure read, create/update, and delete permissions. Reissuing a key invalidates the old key immediately. Store the key in a server-side environment variable or equivalent secret storage. Do not put it in a web page or distributed app.

Make your first request

If the map URL is https://metamaps.jp/d/example, its API {slug} is example. This request retrieves the permissions, features, and limits available to the connection. Replace example and set the environment variable for your map.

curl --fail-with-body \
  'https://metamaps.jp/api/integrations/v2/maps/example/capabilities' \
  -H "X-Api-Key: ${METAMAPS_API_KEY}"

You can also retrieve the map's spots.

curl --fail-with-body \
  'https://metamaps.jp/api/integrations/v2/maps/example/spots' \
  -H "X-Api-Key: ${METAMAPS_API_KEY}"

Available data

Data	Operations	Reference
Spots and pictograms	Read, create, update, delete, and convert types	Spot API reference
Images	Read, register, update, and delete user images; read presets	Image API reference
Events and timetables	Read, create, update, and delete	Event API reference
Congestion and wait times	Read and update current values	Congestion API reference

Configure congestion definitions and spot assignments in the admin console. Each spot supports up to two different definitions. Select the target status with its expectedDefinitionKey; the current-value API does not change definitions, assignments, or priority.

Before updating a record

Read capabilities to check permissions and available features, then use references to retrieve floors, categories, display sets, and other reference values. Updating an existing spot requires its retrieved ETag in the If-Match header. If a conflict occurs, retrieve the latest record and review your change.

Some image mutations run asynchronously. Follow the operation returned in the response to check their status. See the API reference for required headers, status codes, pagination, and asynchronous operations.

Errors and retries

Response	What to check
`401 unauthorized`	API key, map slug, and whether the map is available
`403 forbidden`	Permissions required for the operation
`429 Too Many Requests`	Wait for the number of seconds in `Retry-After` before retrying

For periodic syncs, use paginated list requests and write only records that changed. Consult the reference for each API's rate limit and operation-specific errors.

API reference and OpenAPI

Browse the API reference for every operation's inputs, responses, and code examples. Download the OpenAPI definition to use it with integration tools or client generators.