# 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](/developers/embed/); for a mobile app, use the [SDK](/developers/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.

```text
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.

```bash
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.

```bash
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](/api-v2/#tag/v2-spots) |
| Images | Read, register, update, and delete user images; read presets | [Image API reference](/api-v2/#tag/v2-images) |
| Events and timetables | Read, create, update, and delete | [Event API reference](/api-v2/#tag/events) |
| Congestion and wait times | Read and update current values | [Congestion API reference](/api-v2/#tag/congestion) |

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](/api-v2/) 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](/api-v2/) for every operation's inputs, responses, and code examples. [Download the OpenAPI definition](/api-v2/metamap-public-api.yaml) to use it with integration tools or client generators.