# Place search (public, no key)

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

The same answer as GET /geo/search without a key, for a birthplace field in a widget or a static page: candidates with coordinates, IANA zone, population and names in our 21 languages. Costs 1 unit of the public bucket (30 an hour per address without a key), so search after the visitor pauses typing rather than on every key. `Cache-Control: public, max-age=86400`. Attribution is in the body: displaying the data carries the GeoNames CC BY 4.0 credit. Reverse lookup and the offset on a date stay keyed (GET /geo/reverse, GET /geo/timezone).

Group: Public. Auth: none, this endpoint answers without a key.

## 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 | OK |
| 400 | Invalid sign or date |

### 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 'https://api.astroway.info/v1/public/geo/search?q=Kiev&lang=uk&limit=1'
```

---

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