# List locations

`GET /api/v1/locations`

List every location of your account, each one followed by the locations inside it.

A location is a place: a town, a house, a room, a shelf, a box. It belongs to the account, not to a vault, since one house holds the things of every vault.

The order is the one the settings screen shows: each location comes before the locations inside it, and the locations at each level are sorted by name. Paging slices that order, so a page may begin inside a location listed on the page before.

This endpoint also answers QUERY, with the same parameters sent in the request body. [How QUERY works](https://my.monicahq.com/docs/api/query-method).

## Query parameters

- `page` (integer, optional, defaults to 1): Which page to answer with.
- `per_page` (integer, optional, defaults to 25): How many locations one page holds, between 1 and 100. A number outside the range is brought back into it rather than refused.

## Returns

A page of location objects, and how many there are in all. An account with no location answers an empty list.

- `data` (array): The locations on this page. An empty list rather than an error when there are none.
- `data[]` (object): One 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.
- `meta` (object): Where you are in the collection.
- `meta.page` (integer): The page this is, counting from 1.
- `meta.per_page` (integer): How many one page holds, which is the size that was asked for once it has been brought into the allowed range.
- `meta.total` (integer): How many locations there are in all, not how many are on this page.

## 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 \
  -H "Authorization: Bearer $MONICA_TOKEN"
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/locations', {
  headers: { Authorization: `Bearer ${token}` },
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->get('https://my.monicahq.com/api/v1/locations');
```

## Response

`200`

```json
{
    "data": [
        {
            "type": "location",
            "id": "5b7e2c90-4d18-4a3f-9e61-0c8d2f7a1b43",
            "attributes": {
                "parent_id": null,
                "name": "Dunder Mifflin Scranton",
                "emoji": "🏢",
                "address": "1725 Slough Avenue\nScranton, PA 18505",
                "path": "Dunder Mifflin Scranton",
                "effective_address": {
                    "address": "1725 Slough Avenue\nScranton, PA 18505",
                    "location_id": "5b7e2c90-4d18-4a3f-9e61-0c8d2f7a1b43",
                    "location_name": "Dunder Mifflin Scranton"
                },
                "location_count": 1,
                "created_at": 1761350400,
                "updated_at": 1761354000
            },
            "links": {
                "self": "https://my.monicahq.com/api/v1/locations/5b7e2c90-4d18-4a3f-9e61-0c8d2f7a1b43",
                "web": "https://my.monicahq.com/settings/account/locations/5b7e2c90-4d18-4a3f-9e61-0c8d2f7a1b43/edit"
            }
        },
        {
            "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"
            }
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 2
    }
}
```
