> ## Documentation Index
> Fetch the complete documentation index at: https://docs.storerocket.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List locations

> Read a paginated list with supported filters and optional relationships.

Requires `location:read` and project API access. Returns a `data` array with pagination `links` and `meta`.

<ParamField path="project_id" type="string" required>The public project ID returned by [List projects](/api/projects).</ParamField>
<ParamField query="page" type="number" default="1">Positive integer page number to retrieve.</ParamField>
<ParamField query="limit" type="number" default="15">Integer page size from 1 to 100; larger values use the default size.</ParamField>
<ParamField query="includeHours" type="number">Send `1` to include the hours object, or null if there is no schedule.</ParamField>
<ParamField query="includeFilters" type="number">Send `1` to include the filters array.</ParamField>
<ParamField query="includeFields" type="number">Send `1` to include the custom-fields array.</ParamField>
<ParamField query="includeCallsToAction" type="number">Send `1` to include the calls-to-action array.</ParamField>

Omit an include flag or use `0` to leave that relationship out. Use numeric `1`/`0`, rather than the string `false`.

JavaScript examples run in Node.js 22 or later; PHP examples require PHP 8.2 or later with cURL. Both read `STOREROCKET_TOKEN` from your environment. See the [quickstart](/api/quickstart) for setup.

<RequestExample>
  ```bash cURL theme={null}
  curl --get 'https://storerocket.io/api/v2/projects/PROJECT_ID/locations' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Accept: application/json' \
    --data-urlencode 'limit=25' \
    --data-urlencode 'city[eq]=Seattle' \
    --data-urlencode 'includeHours=1'
  ```

  ```javascript JavaScript theme={null}
  const token = process.env.STOREROCKET_TOKEN;
  if (!token) throw new Error("Set STOREROCKET_TOKEN first.");
  const projectId = "PROJECT_ID";

  const url = new URL(`https://storerocket.io/api/v2/projects/${encodeURIComponent(projectId)}/locations`);
  url.searchParams.set("limit", "25");
  url.searchParams.set("city[eq]", "Seattle");
  url.searchParams.set("includeHours", "1");
  const response = await fetch(url, {
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
    },
    signal: AbortSignal.timeout(30_000),
  });

  const text = await response.text();
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
  console.log(JSON.parse(text));
  ```

  ```php PHP theme={null}
  <?php

  $token = getenv("STOREROCKET_TOKEN") ?: throw new RuntimeException("Set STOREROCKET_TOKEN first.");
  $projectId = "PROJECT_ID";

  $url = 'https://storerocket.io/api/v2/projects/' . rawurlencode($projectId) . '/locations';
  $url .= "?" . http_build_query([
      'limit' => 25,
      'city[eq]' => 'Seattle',
      'includeHours' => 1,
  ], "", "&", PHP_QUERY_RFC3986);

  $curl = curl_init($url);
  curl_setopt_array($curl, [
      CURLOPT_HTTPHEADER => [
          "Authorization: Bearer $token",
          "Accept: application/json",
      ],
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_CONNECTTIMEOUT => 5,
      CURLOPT_TIMEOUT => 30,
  ]);

  $text = curl_exec($curl);
  $error = curl_error($curl);
  $status = (int) curl_getinfo($curl, CURLINFO_HTTP_CODE);
  curl_close($curl);

  if ($text === false) {
      throw new RuntimeException("Request failed: $error");
  }
  if ($status < 200 || $status >= 300) {
      throw new RuntimeException("HTTP $status: $text");
  }
  $data = json_decode($text, false, 512, JSON_THROW_ON_ERROR);
  echo json_encode($data, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR), PHP_EOL;
  ```
</RequestExample>

## Supported filters

| Field | Operators |
| - | - |
| `name` | `eq`, `ne`, `like` |
| `address` | `eq`, `like` |
| `city` | `eq`, `like` |
| `state` | `eq`, `like` |
| `country` | `eq`, `like` |
| `postalCode` | `eq` |

Use bracket notation, such as `city[eq]=Seattle` or `name[like]=Downtown`. `like` matches a substring. Supplied filters are combined.
The query field is `postalCode`, although the location response uses `postcode`. Plain `city=Seattle`, `postcode=98101`, and `visible` are not supported list filters.
Use `--data-urlencode` in curl for bracketed parameters.

## Response

Each element of `data` uses the [location response format](/api/locations/get#response-format). Follow `links.next` until it is null, or use `meta.current_page` and `meta.last_page`.

The example below uses `limit=1` with two locations. Location fields and `meta.links` are shortened for readability; the request example above uses `limit=25` and filters.

<ResponseExample>
  ```json Example response theme={null}
  {
    "data": [
      {
        "id": "LOCATION_ID",
        "name": "Downtown Store",
        "city": "Seattle"
      }
    ],
    "links": {
      "first": "https://storerocket.io/api/v2/projects/PROJECT_ID/locations?limit=1&page=1",
      "last": "https://storerocket.io/api/v2/projects/PROJECT_ID/locations?limit=1&page=2",
      "prev": null,
      "next": "https://storerocket.io/api/v2/projects/PROJECT_ID/locations?limit=1&page=2"
    },
    "meta": {
      "current_page": 1,
      "from": 1,
      "last_page": 2,
      "path": "https://storerocket.io/api/v2/projects/PROJECT_ID/locations",
      "per_page": 1,
      "to": 1,
      "total": 2
    }
  }
  ```
</ResponseExample>

Keep the same filters and include flags on every page. An empty result has `"data": []`; stop once `links.next` is null. The [sync guide](/api/sync-locations#read-every-page) includes a working pagination loop.

Errors: `401` authentication, `403` access/permission, `404` inaccessible project, `429` rate limit. See [errors](/api/errors).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.