---
title: "Find cities and regions available for monitoring in a market"
method: GET
path: "/locations"
tags: ["Projects"]
---

# Find cities and regions available for monitoring in a market

`GET /locations`

## Request

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

Searches the locations that can be monitored inside one country, such as states, regions and cities, for the chosen search engines (a location must be supported by every engine selected). Without query it returns the country and the most common locations. With main_cities=true it returns only the market's main cities (United States, United Kingdom and Spain), which fills a project's location list quickly; other markets return none. Pass the returned code and name in locations to create_project or update_project.

## Query parameters

- `country` string, required: ISO 3166-1 alpha-2, such as US.
- `query` string: Part of a name, such as new york.
- `engine` union: Search engines the locations must support. Defaults to every engine the market offers.
  - 'google' | 'bing'
  - string[]
- `limit` integer: Locations to return, 1 to 100.
- `main_cities` union: Only the market's main cities, as the app's Add main cities button adds them. Ignores query.
  - boolean
  - 'true' | 'false'

## Response `200`

Find cities and regions available for monitoring in a market

- object
  - `country` string, required
  - `search_engines` string[], required
  - `total_matches` integer, required
  - `data` object[], required
    - `code` integer, required: Pass as locations[].code to update_project or create_project.
    - `name` string, required: Full name, such as New York,New York,United States.
    - `label` string, required: The name the app shows.
    - `type` string, nullable, required: Such as Country, State or City.
  - `request_id` string

## Other responses

- `400`: Invalid parameters, cursor or body.
- `401`: Missing, invalid, expired or revoked credential.
- `403`: The credential lacks the write scope, the plan does not include the API, or the allowance is used up.
- `404`: Unknown project, keyword or run in this account.
- `409`: The idempotency key was already used for a different request.
- `429`: Rate limit reached. Retry after the Retry-After seconds.
- `503`: The requested service or file is temporarily unavailable.

---

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