---
title: "Search locations by name"
method: GET
path: "/locations/search"
tags: ["Locations"]
---

# Search locations by name

`GET /locations/search`

Returns a paginated list of locations whose name matches the supplied query term. Results are suitable for autocomplete dropdowns on the Groups list page. Requires the READ_LOCATION permission. Returns an empty result set (200) when the location-search feature is disabled for this environment.

## Query parameters

- `page` integer
- `q` string, required
- `size` integer

## Headers

- `tenant-id` string, required

## Response `200`

Paginated list of matching locations

- LocationSearchPagedResponse — Paginated list of location search results.
  - `data` LocationSearchResult[], required — Locations matching the search term.
    - `id` string, required — certifyLocationId — the stored reference for a selected location.
    - `name` string, required — Location display name.
  - `totalCount` integer — Total number of matching locations across all pages.

## Other responses

- `400` — Invalid request. Validation failures (q length / pagination) and missing `tenant-id` both return `{"errors":[{"httpStatus", "reason", "title", "detail"}]}`. Examples: q too short → reason=VALIDATION_ERROR; missing tenant-id → title=Missing Headers.
- `401` — Unauthorized — missing or invalid bearer token. Body is not a structured ApiError (Quarkus/OIDC challenge; typically empty).
- `403` — Forbidden — caller lacks the READ_LOCATION permission. Body is ApiError (AuthorizationFilter ForbiddenException → GlobalExceptionMapper), e.g. `{"errors":[{"httpStatus":403,"reason":"Forbidden","title":"Request Failed","detail":"An error occurred processing your request"}]}`.

---

[API](https://skmtc.net/certifyos/apis/certify-api-layer.md) · [All operations](https://skmtc.net/certifyos/apis/certify-api-layer/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/certifyos/certify-api-layer/revisions/563848e0ecc0/schema)