# Locations

> Manage location embeds. Create a location with its address and coordinates, update fields as needed, and fetch a paste-ready HTML iframe snippet to embed an interactive map on your website.

Source: https://docs.oursprivacy.com/docs/platform-api/locations

Manage location embeds. Create a location with its address and coordinates, update fields as needed, and fetch a paste-ready HTML iframe snippet to embed an interactive map on your website.

## GET /rest/v1/locations

List every location for this account. Not paginated — each account has a small map-count limit (single digits in practice) so the response always fits in a single page. Requires API-key scope or current OAuth user permission: maps:list

Request URL: `GET https://app.oursprivacy.com/rest/v1/locations`

Authentication: apiKey or oauth2.

### Responses

- `200`: List of locations
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entities` | object[] | Yes |  |
| `entities[].id` | string | Yes |  |
| `entities[].accountId` | string | Yes |  |
| `entities[].mapName` | string \| null | No |  |
| `entities[].customDomain` | string \| null | No |  |
| `entities[].name` | string \| null | No |  |
| `entities[].line1` | string \| null | No |  |
| `entities[].line2` | string \| null | No |  |
| `entities[].city` | string \| null | No |  |
| `entities[].state` | string \| null | No |  |
| `entities[].zip` | string \| null | No |  |
| `entities[].country` | string \| null | No |  |
| `entities[].phoneNumber` | string \| null | No |  |
| `entities[].websiteUrl` | string \| null | No |  |
| `entities[].websiteLinkText` | string \| null | No |  |
| `entities[].latitude` | number \| null | No |  |
| `entities[].longitude` | number \| null | No |  |
| `entities[].additionalAddresses` | object[] \| null | No |  |
| `entities[].additionalAddresses[].name` | string \| null | No |  |
| `entities[].additionalAddresses[].line1` | string \| null | No |  |
| `entities[].additionalAddresses[].line2` | string \| null | No |  |
| `entities[].additionalAddresses[].city` | string \| null | No |  |
| `entities[].additionalAddresses[].state` | string \| null | No |  |
| `entities[].additionalAddresses[].zip` | string \| null | No |  |
| `entities[].additionalAddresses[].country` | string \| null | No |  |
| `entities[].additionalAddresses[].phoneNumber` | string \| null | No |  |
| `entities[].additionalAddresses[].websiteUrl` | string \| null | No |  |
| `entities[].additionalAddresses[].websiteLinkText` | string \| null | No |  |
| `entities[].additionalAddresses[].latitude` | number \| null | No |  |
| `entities[].additionalAddresses[].longitude` | number \| null | No |  |
| `entities[].center` | object \| null | No |  |
| `entities[].center.latitude` | number | Yes |  |
| `entities[].center.longitude` | number | Yes |  |
| `entities[].createdAt` | string \| null | No |  |
| `entities[].updatedAt` | string \| null | No |  |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## POST /rest/v1/locations

Create a new location (map embed). All address fields are optional and can be filled in later via PATCH. Returns the slim entity with the server-assigned `id` so callers can immediately request `GET /rest/v1/locations/{id}/embed-code`. Requires API-key scope or current OAuth user permission: maps:create

Request URL: `POST https://app.oursprivacy.com/rest/v1/locations`

Authentication: apiKey or oauth2.

### Request body (`application/json`, required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mapName` | string \| null | No |  |
| `customDomain` | string \| null | No |  |
| `name` | string \| null | No |  |
| `line1` | string \| null | No |  |
| `line2` | string \| null | No |  |
| `city` | string \| null | No |  |
| `state` | string \| null | No |  |
| `zip` | string \| null | No |  |
| `country` | string \| null | No |  |
| `phoneNumber` | string \| null | No |  |
| `websiteUrl` | string \| null | No |  |
| `websiteLinkText` | string \| null | No |  |
| `latitude` | number \| null | No |  |
| `longitude` | number \| null | No |  |
| `additionalAddresses` | object[] \| null | No |  |
| `additionalAddresses[].name` | string \| null | No |  |
| `additionalAddresses[].line1` | string \| null | No |  |
| `additionalAddresses[].line2` | string \| null | No |  |
| `additionalAddresses[].city` | string \| null | No |  |
| `additionalAddresses[].state` | string \| null | No |  |
| `additionalAddresses[].zip` | string \| null | No |  |
| `additionalAddresses[].country` | string \| null | No |  |
| `additionalAddresses[].phoneNumber` | string \| null | No |  |
| `additionalAddresses[].websiteUrl` | string \| null | No |  |
| `additionalAddresses[].websiteLinkText` | string \| null | No |  |
| `additionalAddresses[].latitude` | number | Yes |  |
| `additionalAddresses[].longitude` | number | Yes |  |
| `center` | object \| null | No |  |
| `center.latitude` | number | Yes |  |
| `center.longitude` | number | Yes |  |

### Responses

- `200`: Created location
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `409`: Conflict — the account has reached its map count limit. Reason is in the response `error` field.
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes |  |
| `accountId` | string | Yes |  |
| `mapName` | string \| null | No |  |
| `customDomain` | string \| null | No |  |
| `name` | string \| null | No |  |
| `line1` | string \| null | No |  |
| `line2` | string \| null | No |  |
| `city` | string \| null | No |  |
| `state` | string \| null | No |  |
| `zip` | string \| null | No |  |
| `country` | string \| null | No |  |
| `phoneNumber` | string \| null | No |  |
| `websiteUrl` | string \| null | No |  |
| `websiteLinkText` | string \| null | No |  |
| `latitude` | number \| null | No |  |
| `longitude` | number \| null | No |  |
| `additionalAddresses` | object[] \| null | No |  |
| `additionalAddresses[].name` | string \| null | No |  |
| `additionalAddresses[].line1` | string \| null | No |  |
| `additionalAddresses[].line2` | string \| null | No |  |
| `additionalAddresses[].city` | string \| null | No |  |
| `additionalAddresses[].state` | string \| null | No |  |
| `additionalAddresses[].zip` | string \| null | No |  |
| `additionalAddresses[].country` | string \| null | No |  |
| `additionalAddresses[].phoneNumber` | string \| null | No |  |
| `additionalAddresses[].websiteUrl` | string \| null | No |  |
| `additionalAddresses[].websiteLinkText` | string \| null | No |  |
| `additionalAddresses[].latitude` | number \| null | No |  |
| `additionalAddresses[].longitude` | number \| null | No |  |
| `center` | object \| null | No |  |
| `center.latitude` | number | Yes |  |
| `center.longitude` | number | Yes |  |
| `createdAt` | string \| null | No |  |
| `updatedAt` | string \| null | No |  |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## PATCH /rest/v1/locations/{id}

Partially update a location. Only the fields you send are changed. `additionalAddresses` is replaced wholesale when sent — partial item updates are not merged. The map's computed center is recalculated on every PATCH from the latest coordinates. Requires API-key scope or current OAuth user permission: maps:update

Request URL: `PATCH https://app.oursprivacy.com/rest/v1/locations/{id}`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes |  |

### Request body (`application/json`, required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mapName` | string \| null | No |  |
| `customDomain` | string \| null | No |  |
| `name` | string \| null | No |  |
| `line1` | string \| null | No |  |
| `line2` | string \| null | No |  |
| `city` | string \| null | No |  |
| `state` | string \| null | No |  |
| `zip` | string \| null | No |  |
| `country` | string \| null | No |  |
| `phoneNumber` | string \| null | No |  |
| `websiteUrl` | string \| null | No |  |
| `websiteLinkText` | string \| null | No |  |
| `latitude` | number \| null | No |  |
| `longitude` | number \| null | No |  |
| `additionalAddresses` | object[] \| null | No |  |
| `additionalAddresses[].name` | string \| null | No |  |
| `additionalAddresses[].line1` | string \| null | No |  |
| `additionalAddresses[].line2` | string \| null | No |  |
| `additionalAddresses[].city` | string \| null | No |  |
| `additionalAddresses[].state` | string \| null | No |  |
| `additionalAddresses[].zip` | string \| null | No |  |
| `additionalAddresses[].country` | string \| null | No |  |
| `additionalAddresses[].phoneNumber` | string \| null | No |  |
| `additionalAddresses[].websiteUrl` | string \| null | No |  |
| `additionalAddresses[].websiteLinkText` | string \| null | No |  |
| `additionalAddresses[].latitude` | number | Yes |  |
| `additionalAddresses[].longitude` | number | Yes |  |
| `center` | object \| null | No |  |
| `center.latitude` | number | Yes |  |
| `center.longitude` | number | Yes |  |

### Responses

- `200`: Updated location
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes |  |
| `accountId` | string | Yes |  |
| `mapName` | string \| null | No |  |
| `customDomain` | string \| null | No |  |
| `name` | string \| null | No |  |
| `line1` | string \| null | No |  |
| `line2` | string \| null | No |  |
| `city` | string \| null | No |  |
| `state` | string \| null | No |  |
| `zip` | string \| null | No |  |
| `country` | string \| null | No |  |
| `phoneNumber` | string \| null | No |  |
| `websiteUrl` | string \| null | No |  |
| `websiteLinkText` | string \| null | No |  |
| `latitude` | number \| null | No |  |
| `longitude` | number \| null | No |  |
| `additionalAddresses` | object[] \| null | No |  |
| `additionalAddresses[].name` | string \| null | No |  |
| `additionalAddresses[].line1` | string \| null | No |  |
| `additionalAddresses[].line2` | string \| null | No |  |
| `additionalAddresses[].city` | string \| null | No |  |
| `additionalAddresses[].state` | string \| null | No |  |
| `additionalAddresses[].zip` | string \| null | No |  |
| `additionalAddresses[].country` | string \| null | No |  |
| `additionalAddresses[].phoneNumber` | string \| null | No |  |
| `additionalAddresses[].websiteUrl` | string \| null | No |  |
| `additionalAddresses[].websiteLinkText` | string \| null | No |  |
| `additionalAddresses[].latitude` | number \| null | No |  |
| `additionalAddresses[].longitude` | number \| null | No |  |
| `center` | object \| null | No |  |
| `center.latitude` | number | Yes |  |
| `center.longitude` | number | Yes |  |
| `createdAt` | string \| null | No |  |
| `updatedAt` | string \| null | No |  |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## GET /rest/v1/locations/{id}/embed-code

Generate the paste-ready HTML embed snippet for a location. The response is a single self-contained HTML string (a `<style>` block + `<div>` wrapping an `<iframe>` pointed at the Ours Privacy maps CDN, plus an optional JSON-LD `<script>`). Customize the render with the optional query params (`color`, `theme`, `colorScheme`, `mapStyle`, `includeAddressBox`, `zoom`, `includeControls`, `includeSEOSchema`); all have sane defaults. Requires API-key scope or current OAuth user permission: maps:find

Request URL: `GET https://app.oursprivacy.com/rest/v1/locations/{id}/embed-code`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes |  |
| `color` | query | string | No | Brand color used in the embedded map UI. Any CSS color string. |
| `theme` | query | string | No | Visual theme variant. One of: `"default"`, `"modern"`. |
| `colorScheme` | query | string | No | Light or dark color scheme. One of: `"light"`, `"dark"`. |
| `mapStyle` | query | string | No | Base map style. One of: `"Standard"`, `"Monochrome"`. |
| `includeAddressBox` | query | boolean | No | Render the address sidebar overlay next to the map. Send `false` to hide. |
| `zoom` | query | integer | No | Initial map zoom level (Google-style 1–20). |
| `includeControls` | query | string | No | Whether the embed renders map controls. `accessible` enables keyboard-navigable controls. One of: `"yes"`, `"no"`, `"accessible"`. |
| `includeSEOSchema` | query | boolean | No | Emit a `schema.org` Place JSON-LD block alongside the iframe so search engines can index the location. |

### Responses

- `200`: Embed code HTML for the location
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `embedCode` | string | Yes | Self-contained HTML snippet (a `<style>` + `<div>` wrapping an `<iframe>`, plus an optional JSON-LD `<script>`) ready to paste into any page. The iframe `src` points to the maps CDN for the current stage. |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).