---
title: "List locations"
method: GET
path: "/api/v1/locations"
tags: ["Locations"]
---

# List locations

`GET /api/v1/locations`

## Request

- Base URL: `https://api.mapulus.com`
- URL: `https://api.mapulus.com/api/v1/locations`
- Auth: HTTP bearer

This endpoint returns all locations in the account. <br>
         <br>
        The results can be filtered by:  <br>
        <ul>
        <li>Map ID</li>
        <li>Layer ID</li>
        <li>External ID</li>
        <li>Nearest: Returns up to the 24 closest locations from a provided <b>latitude</b> and <b>longitude</b> or <b>address</b> and travel <b>profile</b> ("driving", "cycling", "walking"). This can be sorted by <b>time</b> or <b>distance</b>. Note: If the source location is on water or inaccessible, the server will respond with the nearest locations by direct line and not include a duration or distance.</li>
        </ul>
        Example request:
```
curl --location --request GET 'https://api.mapulus.com/api/v1/locations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your-token>' \
--data '{
    "map_id": "<your-map-id>",
    "nearest": {
      "lat": "-27.52851640781164",
      "lon": "152.97921775875503",
      "sort_by": "time",
      "profile": "driving",
      "limit": "10"
    }
}'

## Query parameters

- `map_id` string
- `layer_id` string
- `external_id` string
- `nearest[lat]` number
- `nearest[lon]` number
- `nearest[address]` number
- `nearest[sort_by]` string
- `nearest[profile]` string
- `nearest[live_traffic]` string
- `nearest[limit]` integer

## Response `200`

Succcess: Returns all locations in account.

- object
  - `object` string, required
  - `data` object[], required
    - `object` string, required
    - `id` string, uuid, required
    - `lat` number, float, nullable, required
    - `lon` number, float, nullable, required
    - `label` string, nullable
    - `title` string, nullable
    - `address` string, nullable
    - `external_id` string, nullable
    - `geocoding_error` boolean, nullable
    - `geocoding_error_type` string, nullable
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `travel_contour` boolean, nullable
    - `contour_mode` string, nullable
    - `contour_metric` string, nullable
    - `contour_style` string, nullable
    - `contour_minutes` string, nullable
    - `map_id` string, uuid, required
    - `layer_id` string, uuid, required
    - `custom_attributes` object[], required
      - `object` string, required
      - `name` string, required
      - `value` string, nullable, required
      - `custom_attribute_id` string, uuid, required
      - `custom_attribute_value_id` string, uuid, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
  - `pages` object
    - `object` string, required
    - `total_pages` number, required
    - `current_page` number, required
    - `next_page` number, nullable
    - `prev_page` number, nullable
  - `total_count` integer

## Other responses

- `401`: Unauthorized: Invalid API Key or does not have the correct perimission to access resource.
- `422`: Unprocessable Entity: The request because the request was well-formed, but for example the map_id or layer_id is not valid.

---

[API](https://skmtc.dev/mapulus/apis/mapulus-api.md) · [All operations](https://skmtc.dev/mapulus/apis/mapulus-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mapulus/apis/mapulus-api/revisions/b99766fa053f?raw)