# Place search

`GET https://api.astroway.info/v1/geo/search`

A place name to candidates with coordinates and the IANA zone, for a birthplace field. Matches a prefix, ignores case, accents and punctuation (`krakow` finds Kraków, `St. Petersburg` finds Saint Petersburg), and knows the names GeoNames carries in our 21 languages and older ones such as Kiev. Ranked by population, an exact name counting ten times its size, so an ambiguous name such as Springfield lists every town largest first; `q=Springfield, Illinois` or `Springfield, MA` narrows by region or country after the comma. `lang` names the place, region and country in that language where the data has the name; `originalName` is then the GeoNames name. Covers populated places of 1000 people or more plus administrative seats, about 172 000 places: a smaller village is absent, not misspelled. Attribution is in the body because displaying the data carries the CC BY credit. A keyless twin for widgets is GET /public/geo/search.

Group: Astro-Geography. Auth: `X-Api-Key` header. Operation ID: `geo_search_get`.

## Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `q` | query | yes | string | Place name or its beginning, in any of our languages and scripts. Case, accents and punctuation are ignored. Text after the first comma narrows by region or country instead: `Springfield, Illinois`, `Springfield, MA`, `Paris, US`. |
| `lang` | query | no | "uk" \| "en" \| "de" \| "pl" \| "es" \| "pt" \| "fr" \| "it" \| … | Language for `name`, `admin1` and `country`. Where GeoNames has no name in it, the GeoNames name stays. Matching always covers every language. |
| `limit` | query | no | integer | How many candidates to return. |
| `country` | query | no | string | Restrict to these ISO 3166-1 alpha-2 codes, comma separated, up to 20. |
| `fields` | query | no | string | Comma-separated dotted paths, relative to `data`, to keep in the response. A path is applied to every element of an array, so `planets.name` means the name of each planet. Paths that match nothing come back in `_fields_unmatched`; a list where nothing matches at all is a 400, because an empty object would be a confident wrong answer. |
| `precision` | query | no | integer | Round every non-integer number in the response to this many decimal places. Integers are left alone, because an id is not a measurement. Ecliptic longitudes ship with fourteen decimals by default; 2 is about a tenth of an arcminute. |

## Responses

| Status | Meaning |
|---|---|
| 200 | Successful calculation |
| 400 | Validation error |
| 401 | Missing or invalid API key |

### Success fields, under `data`

| Field | Type | Required | Description |
|---|---|---|---|
| `query` | string | no |  |
| `lang` | string | no |  |
| `count` | number | no |  |
| `results` | object[] | no |  |
| `note` | string | no |  |
| `dataset` | object | no |  |
| `dataset.source` | string | no |  |
| `dataset.url` | string | no |  |
| `dataset.namesUrl` | string | no |  |
| `dataset.licence` | string | no |  |
| `dataset.downloaded` | string | no |  |
| `dataset.count` | number | no |  |
| `attribution` | object | no |  |
| `attribution.source` | string | no |  |
| `attribution.sourceUrl` | string | no |  |
| `attribution.licence` | string | no |  |
| `attribution.licenceUrl` | string | no |  |
| `attribution.notice` | string | no |  |

## Example

```bash
curl -X GET https://api.astroway.info/v1/geo/search?q=Kiev \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json"
```

---

Rendered from https://api.astroway.info/v1/openapi.json. HTML page: https://api.astroway.info/docs/api/operations/geo_search_get/