---
title: "Search a pinned self-hosted place catalog"
method: POST
path: "/api/astro/place-search"
tags: ["Calculations"]
---

# Search a pinned self-hosted place catalog

`POST /api/astro/place-search`

## Request

- Base URL: `https://api.cosmicephemeris.com`
- URL: `https://api.cosmicephemeris.com/api/astro/place-search`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Searches Cosmic Ephemeris's derived and modified pinned GeoNames cities15000 snapshot without a request-time network dependency. Returns up to ten ordered candidates with coordinates, IANA timezone, dataset version, source ID, direct source and CC BY 4.0 links, and attribution. A result is a candidate, not an automatically selected birthplace. One standard quota unit per admitted request; failed or timed-out admitted attempts are not refunded.

## Request body

- PlaceSearchRequest
  - `query` string, required
  - `country_codes` string[]
  - `limit` integer

## Response `200`

Ordered place candidates.

- PlaceSearchResponse
  - `type` 'place_search', required
  - `status` 'current', required
  - `query` string, required
  - `results` PlaceCandidate[], required
    - `place_id` string, required
    - `display_name` string, required
    - `country_code` string, required
    - `admin1` string
    - `lat` union, required: WGS84 decimal latitude. JSON numbers are recommended; numeric strings are accepted by the current engine, then checked for finiteness/range. Exact poles and undefined Ascendant geometry return 400; supported successful latitude is strictly between -90 and 90. Boolean/null/object/array coordinates are invalid.
      - number
      - string
    - `lon` union, required: WGS84 decimal longitude, east positive, within [-180,180]. JSON numbers are recommended; numeric strings are accepted then checked for finiteness/range.
      - number
      - string
    - `timezone` string, nullable, required: IANA timezone name (for example America/New_York). Omission, null, or empty string means UTC for a birth input. Nonexistent or ambiguous local clock-change times return 400; provide the known UTC date/time with timezone UTC instead.
    - `provenance` PlaceProvenance, required
      - `provider` 'geonames-self-hosted', required
      - `dataset_version` '2026-10-02', required
      - `source_id` string, required
      - `license_id` 'CC-BY-4.0', required
      - `attribution` string, required
  - `result_count` integer, required
  - `metadata` object, required

## Other responses

- `400`: Invalid request, malformed JSON, out-of-range date/location, unknown model, invalid timezone or ambiguous/nonexistent clock-change time. Invalid attempts reaching quota reservation consume one unit.
- `401`: Missing, invalid, revoked API key or unavailable activated key owner. Dashboard cookies do not authenticate calculation routes.
- `403`: Origin not allowed by production CORS policy. Server-to-server requests can omit Origin.
- `429`: Monthly quota exhausted, per-user two-request concurrency reached, or nginx rate/connection admission refused. Retry-After: 2 is sent for application per-user concurrency only, not a promise that monthly quota resets in two seconds.
- `502`: Engine unavailable, unsuccessful internal server response or invalid upstream JSON. No engine internals are exposed.
- `503`: Four-request global calculation pool full (Retry-After: 2), maintenance or upstream service unavailable.
- `504`: Application engine timeout: 15 seconds normally; planetary events, house ingresses, aspect windows, event calendar, eclipse geometry, electional search, and event-rule search use 30 seconds; Nakshatra Timeline plus the explicitly enumerated readiness, robustness, location, uncertainty, and electional-audit family use 60 seconds. Timer includes response-body parsing; an admitted timeout consumes quota.

---

[API](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api.md) · [All operations](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api/revisions/f041e924cea3?raw)