---
title: "Find location ids"
method: GET
path: "/v1/lookups/locations"
tags: ["Search"]
---

# Find location ids

`GET /v1/lookups/locations`

## Request

- Base URL: `https://api.recruitmcp.com`
- URL: `https://api.recruitmcp.com/v1/lookups/locations`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://recruitmcp.com/oauth/authorize`, token URL `https://recruitmcp.com/oauth/token`, scopes: `sourcing:read`)

Turns a place name into geo_ids for people search filters. Free, including a place this server has not seen before. The result is cached. This call never charges. An empty result includes a hint. A region name points at a city or the country.

Scope: `sourcing:read`.

## Query parameters

- `q` string, required
- `prefer_area` boolean
- `limit` integer
- `cursor` string

## Headers

- `RecruitMCP-Version` '2026-10-13'
- `RecruitMCP-Customer` string

## Response `200`

Matches, best first.

- LocationList
  - `object` 'list', required
  - `data` Location[], required
    - `geo_id` string, required
    - `title` string, required
    - `is_area` boolean
  - `next_cursor` string, nullable, required: Pass as cursor for the next page. Null on the last page.
  - `has_more` boolean, required
  - `cost` Cost
    - `credits` integer, required: Credits charged by this call. Whole credits. 0 on an idempotent replay, where the body also has replayed: true and the header Idempotent-Replayed: true.
    - `cached_items` integer: Items read from cache. On a replay, the value of the first response.
    - `live_items` integer: Items fetched live by this call. 0 on a replay.
    - `upstream_calls` integer: Index calls made by this call. 0 on a replay.
  - `hint` string: Set when the place has no city id. The country is not returned as a silent stand-in.
  - `fallback` 'country': country when the only match was a country. data stays empty.

## Other responses

- `400`: `invalid_request` (do not retry): A field is missing or has a value this endpoint does not accept. `unsupported_version` (do not retry): RecruitMCP-Version is not a supported version.
- `401`: `unauthorized` (do not retry): Missing bearer API key.
- `402`: `free_tier_limit` (do not retry): This workspace has used its free upstream allowance.
- `403`: `forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.
- `429`: `rate_limited` (retry): Per-key rate limit exceeded. `upstream_busy` (retry): The profile source is busy. Retry after the delay.
- `502`: `upstream_busy` (retry): The profile source is busy. Retry shortly. `upstream_error` (retry): The profile source returned a response that could not be used. Retry later.
- `503`: `upstream_busy` (retry): The profile source is paused.

## Changes

- **2026-10-20** `ad27b35513a6`: 7 warning
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `400`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `401`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `402`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `403`
  - …3 more

[Operation history](https://skmtc.dev/recruitmcp/apis/recruitmcp-api/changes/v1/lookups/locations/get.md)

---

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