# Add a location

`POST /api/v1/locations`

Add a location at the top level, or inside another one.

Start with a home or a building, then add the rooms and the furniture inside it, sending the id of each as the parent_id of the next.

The change is written to the account log.

## Body parameters

- `name` (string, required): What the location is called. Up to 255 characters. Markup and surrounding blank space are stripped, and a name left with nothing in it is refused.
- `parent_id` (uuid, optional): The location it sits inside. Null puts it at the top level, and so does leaving it out of a new location. A location of somebody else is refused, and so is the location itself or one inside it.
- `emoji` (string, optional): Exactly one emoji. A family, a flag or a skin tone counts as one. Letters, or two emoji, are refused.
- `address` (string, optional): Free text over several lines, up to 2,000 characters. Without one, the location uses the address of the nearest location around it that has one.

## Returns

The location object that was added.

- `data` (object): The location.
- `data.type` (string): Always location. It names the kind of record, so a caller holding several kinds can tell them apart without looking at where they came from.
- `data.id` (string): The id of this record, as a string even when it reads as a number. It is what every endpoint naming this record takes.
- `data.attributes` (object): Everything the record holds.
- `data.attributes.parent_id` (uuid): The location it sits inside, or null at the top level.
- `data.attributes.name` (string): What the location is called: a town, a house, a room, a shelf, a box. Two locations may share a name; the path tells them apart.
- `data.attributes.emoji` (string): One emoji shown in place of the default icon, or null for none.
- `data.attributes.address` (string): The address written on the location itself, as free text over several lines, or null. Nothing geocodes it.
- `data.attributes.path` (string): Every location from the top level down to this one, joined by " › ". It is how a location is named wherever one is chosen.
- `data.attributes.effective_address` (object): The address that applies to the location: its own, or else that of the nearest location around it that has one. Null when none of them has an address.
- `data.attributes.effective_address.address` (string): The address, as it was written.
- `data.attributes.effective_address.location_id` (uuid): The location the address is written on, which is this one when it has its own.
- `data.attributes.effective_address.location_name` (string): The name of that location.
- `data.attributes.location_count` (integer): How many locations sit directly inside this one. A location holding any cannot be deleted.
- `data.attributes.created_at` (timestamp): When the location was added, as a count of seconds since 1970 rather than a written date.
- `data.attributes.updated_at` (timestamp): When it last changed, as a count of seconds. Equal to created_at until it is changed.
- `data.links` (object): Where to find this record.
- `data.links.self` (string): The absolute address this record is read from.
- `data.links.web` (string): The screen where the location is edited in the application, which opens for somebody signed in rather than for a key. It is the link to give a person.

## Rate limit

Sixty requests per minute, per user, shared by every key and device. Every answer carries the budget left in `X-RateLimit-Remaining`.

## Request

```sh
curl https://my.monicahq.com/api/v1/locations \
  -X POST \
  -H "Authorization: Bearer $MONICA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "Warehouse",
      "parent_id": "5b7e2c90-4d18-4a3f-9e61-0c8d2f7a1b43",
      "emoji": "\ud83d\udce6"
  }'
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/locations', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Warehouse',
    parent_id: '5b7e2c90-4d18-4a3f-9e61-0c8d2f7a1b43',
    emoji: '📦',
  }),
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->post('https://my.monicahq.com/api/v1/locations', [
    'name' => 'Warehouse',
    'parent_id' => '5b7e2c90-4d18-4a3f-9e61-0c8d2f7a1b43',
    'emoji' => '📦',
]);
```

## Response

`201`

```json
{
    "data": {
        "type": "location",
        "id": "e83a1f6d-27c4-4b95-8d02-6f1b9c4e7a58",
        "attributes": {
            "parent_id": "5b7e2c90-4d18-4a3f-9e61-0c8d2f7a1b43",
            "name": "Warehouse",
            "emoji": "📦",
            "address": null,
            "path": "Dunder Mifflin Scranton › Warehouse",
            "effective_address": {
                "address": "1725 Slough Avenue\nScranton, PA 18505",
                "location_id": "5b7e2c90-4d18-4a3f-9e61-0c8d2f7a1b43",
                "location_name": "Dunder Mifflin Scranton"
            },
            "location_count": 0,
            "created_at": 1761354000,
            "updated_at": 1761357600
        },
        "links": {
            "self": "https://my.monicahq.com/api/v1/locations/e83a1f6d-27c4-4b95-8d02-6f1b9c4e7a58",
            "web": "https://my.monicahq.com/settings/account/locations/e83a1f6d-27c4-4b95-8d02-6f1b9c4e7a58/edit"
        }
    }
}
```
