Geolocation¶

Use geolocation before chart creation when a user enters a birth place as free text. The endpoint returns grounded candidates with coordinates and an IANA time zone that can be passed directly to POST /v1/charts.

The service is intentionally hybrid:

the LLM only normalizes the user query into likely place search terms;
Open-Meteo geocoding grounds the result into real coordinates and time zone;
the literal user query is always searched as a fallback;
coordinates and time zones are never invented by the model.

Resolve places — `GET /v1/geolocation/places`¶

Required scope: charts:read

Query parameters¶

Parameter	Type	Required	Notes
`query`	string, 2..200 chars	yes	Free-text place name. Native scripts, typos, transliterations, and partial descriptions are accepted.
`language`	enum	no, default `en`	Preferred language for search terms.
`limit`	integer, 1..20	no, default `6`	Maximum candidates returned after de-duplication.

Request¶

curl "https://api.astrolinkers.com/v1/geolocation/places?query=Novosibirsk&limit=5" \
  -H "Authorization: Bearer $ASTROLINKERS_API_KEY"

Response — `200 OK`¶

{
  "query": "Novosibirsk",
  "candidates": [
    {
      "name": "Novosibirsk",
      "admin1": "Novosibirsk Oblast",
      "country": "Russia",
      "latitude": 55.0415,
      "longitude": 82.9346,
      "timezone": "Asia/Novosibirsk",
      "population": 1419007,
      "label": "Novosibirsk, Novosibirsk Oblast, Russia"
    }
  ]
}

Use the selected candidate like this:

{
  "birth": {
    "moment": "1984-12-21T18:20:00+07:00",
    "latitude": 55.0415,
    "longitude": 82.9346
  },
  "system": "western",
  "house_system": "placidus",
  "ayanamsha": null
}

Empty result¶

If the gazetteer returns no grounded places, the endpoint still returns 200 OK with an empty candidates array:

{
  "query": "unknown place",
  "candidates": []
}

Errors¶

HTTP	`code`	When
422	`invalid_request`	`query` is too short/long, or `limit` is outside `1..20`.
503	`gazetteer_unavailable`	The upstream Open-Meteo geocoding service is unavailable.

Example:

{
  "error": {
    "code": "gazetteer_unavailable",
    "message_key": "errors.geolocation.gazetteer_unavailable",
    "message": "The place gazetteer is temporarily unavailable.",
    "details": {
      "upstream_reason": "upstream unavailable"
    },
    "request_id": "req_01HY7YQ9V9Y9B9Y9B9Y9B9Y9B9"
  }
}