Locations namespace

Reference for worldwide location search behind location inputs such as a job form's office locations.

Use board.locations for a location input: a worldwide search over countries, regions, cities, and localities. It is not limited to places the board's jobs already use; that is board.taxonomy.places.list. These reads are public and rate limited per client and board.

Shared behavior

Every method returns the Board API wire body unchanged and throws BoardApiError for a non-2xx response. The final FetchOptions argument passes abort signals, headers, and framework cache directives through to fetch.

Order is server-ranked. Render the list as returned; do not re-sort.

`board.locations.search`

Search locations worldwide for what the user has typed.

1board.locations.search(
2  query: LocationSearchQuery,
3  options?: FetchOptions,
4): Promise<ListEnvelope<PublicLocation>>

Field	Type	Behavior
`q`	`string`	What the user has typed. Under two characters returns an empty list.
`limit`	`number`	Maximum results (1–10; default 5).
`country`	`string`	Comma-separated ISO 3166-1 alpha-2 codes, for example `'DE,AT'`. Up to 250. Restricts results to those countries; pass the board's `jobForm.location.allowedCountries` to narrow suggestions to the countries the board allows.
`session`	`string`	Required. Opaque id (for example `crypto.randomUUID()`). Generate one per location-field interaction and reuse it across keystrokes and the resolve call. Renew it before 50 provider requests or after 180 seconds, and generate a fresh one for the next interaction.

1const session = crypto.randomUUID();
2const { data } = await board.locations.search({ q: 'berl', session });
3
4for (const location of data) {
5  console.log(location.fullName, location.placeType, location.countryCode);
6}

Result shape

Field	Meaning
`id`	Opaque location id. Complete the pick with `board.locations.resolve({ locationId: id, session })` before using it in a later submission. Shares its id space with `PublicPlace.id`.
`name`	The location's own name, for example `Berlin`.
`fullName`	Name with its parent context, for example `Berlin, Germany`. Show it in the input once picked.
`contextLabel`	Parent context alone, for a secondary line in the list; `null` for a country.
`placeType`	`country`, `region`, `city`, or `locality`.
`countryCode`	ISO 3166-1 alpha-2 code, or `null`.

A missing or private board returns 404. rate_limited means the client is typing faster than the limit allows; debounce input. locations_unavailable (503) means the search is temporarily down.

Call board.locations.resolve as soon as a result is picked. Later job submissions can then send { locationId: location.id } without depending on the original search session. Profile and experience fields that store plain strings should save the resolved fullName.

Related methods: board.taxonomy.places.list for places the board's jobs already use, and board.jobPosting.create for submitting a picked location.

`board.locations.resolve`

Complete a location pick immediately after the user selects a search result.

1board.locations.resolve(
2  input: LocationResolveInput,
3  options?: FetchOptions,
4): Promise<PublicLocation>

Pass the selected result's id as locationId and reuse the exact session sent to search. The server completes the provider session, validates the selected place, and stores its location hierarchy for later submissions. This call always completes the pick, including when the location was stored previously.

1const session = crypto.randomUUID();
2const { data } = await board.locations.search({ q: 'berl', session });
3const picked = data[0];
4
5if (picked) {
6  const location = await board.locations.resolve({
7    locationId: picked.id,
8    session,
9  });
10
11  await board.jobPosting.create({
12    // ...
13    submission: {
14      // ...
15      officeLocations: [{ locationId: location.id }],
16    },
17  });
18}

Generate a fresh session for the next interaction. A malformed, unknown, unsupported, or mismatched id returns locations_invalid_id (400). locations_unavailable (503) means the pick could not be completed; keep the field unresolved and let the user retry or search again.