# Find places (GeoNames) for the `places` filter

`GET https://trawle.com/v1/places`

Cities, metro areas, states, countries and multi-country regions ("EMEA", "Europe", "Anywhere") whose name starts with `q`. Use `items[].id` in `JobQuery.places`; `context` tells homonyms apart.

## Query parameters

- `q` (string, required): Place name. 1 to 100 characters. Example: `copenhagen`.
- `limit` (integer, optional): Default `8`. 1 to 20. Example: `8`.

## Responses

### 200: Best matches first.

- `items` (array<object>, required, PlaceMatch)
  - `id` (integer, required): GeoNames id (regions are negative).
  - `name` (string, required): Example: `Copenhagen`.
  - `country` (string | null, required): ISO 3166-1 alpha-2 country code; null for multi-country regions. Example: `DK`.
  - `kind` (string, required): One of: `city`, `metro`, `admin1`, `country`, `region`.
  - `context` (string | null, required): Where it is, for telling homonyms apart ("Washington, United States").

### 400: Invalid request: see `error.issues` and `error.hint`.

Schema: Error

- `error` (object, required)
  - `code` (string, required): Machine-readable: `invalid_request`, `not_found`, `forbidden`, `rate_limited`, `internal`. Example: `invalid_request`.
  - `message` (string, required): Example: `places: expected an array of GeoNames ids`.
  - `hint` (string, optional): What to do next, e.g. which lookup to call first. Example: `Resolve place names to ids with GET /v1/places?q=`.
  - `issues` (array<object>, optional): Validation problems, one per invalid field.
    - `path` (string, required)
    - `message` (string, required)

## Examples

### cURL

```bash
curl "https://trawle.com/v1/places?q=copenhagen"
```

### TypeScript

```ts
import createClient from "openapi-fetch";

// npx openapi-typescript https://developers.trawle.com/openapi.json -o trawle.d.ts
import type { paths } from "./trawle";

const trawle = createClient<paths>({ baseUrl: "https://trawle.com" });

const { data, error } = await trawle.GET("/v1/places", {
  params: {
    query: {
      q: "copenhagen",
    },
  },
});
```

### Python

```python
import requests

response = requests.get(
    "https://trawle.com/v1/places",
    params={
        "q": "copenhagen",
    },
)
response.raise_for_status()
data = response.json()
```

### Response 200

```json
{
  "items": [
    {
      "id": 2618425,
      "name": "Copenhagen",
      "country": "DK",
      "kind": "city",
      "context": "Capital Region, Denmark"
    }
  ]
}
```

### Response 400

```json
{
  "error": {
    "code": "invalid_request",
    "message": "query.places.0: Invalid input: expected number, received string",
    "hint": "Fix the fields in `issues`. Ids for `places`, `roles` and `companies` come from the lookup endpoints.",
    "issues": [
      {
        "path": "query.places.0",
        "message": "Invalid input: expected number, received string"
      }
    ]
  }
}
```