---
title: "Search Birth Locations"
method: GET
path: "/v2/locations/search"
tags: ["locations-v2"]
---

# Search Birth Locations

`GET /v2/locations/search`

## Request

- Base URL: `https://api.humandesignhub.app`
- URL: `https://api.humandesignhub.app/v2/locations/search`
- Auth: API key in header `X-API-KEY`

Searches GeoNames city candidates for location-aware chart requests. Returns coordinates and the dataset's IANA timezone when available.

## Query parameters

- `query` string, required
- `limit` integer: Maximum number of candidates to return (1–20, default 10).
- `country_code` string, nullable: Optional ISO 3166-1 alpha-2 country code to narrow results (e.g. `US`).

## Response `200`

Successful Response

- LocationSearchResponse
  - `query` string, required
  - `count` integer, required
  - `results` LocationSearchResult[], required
    - `provider_id` integer, nullable: 위치 provider가 반환한 원본 ID
    - `label` string, required: 사용자 표시용 위치 라벨
    - `name` string, required: 도시/장소명
    - `admin1` string, nullable: 1차 행정구역
    - `admin2` string, nullable: 2차 행정구역
    - `country` string, nullable: 국가명
    - `country_code` string, nullable: ISO-3166-1 alpha-2 국가 코드
    - `latitude` number, required: 위도
    - `longitude` number, required: 경도
    - `elevation` number, nullable: 해발 고도(미터)
    - `population` integer, nullable: 인구
    - `timezone` string, nullable: IANA timezone ID
    - `source` string: 위치 데이터 출처

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/humandesignhub/apis/human-design-hub-pro-api.md) · [All operations](https://skmtc.dev/humandesignhub/apis/human-design-hub-pro-api/llms.txt) · [OpenAPI document](https://skmtc.dev/humandesignhub/apis/human-design-hub-pro-api/revisions/c2681d2ac216?raw)