# Geocode a structured address

`GET /geocode`

Geocodes an address given as separate fields, and returns the best match
or no result. `address` is matched on its own, then checked against
`locality`, `region` and `postcode`.

- A house number missing from the data is interpolated between its
  neighbours (`accuracy: interpolated`), or answered with its street
  (`accuracy: street`).
- A street matches `postcode` only when postcode data confirms it.
- A different house is never returned: `10/1367` matches as written or
  as 1367, never as house 10.
- `geocoding.query` is the form of the address that matched, which can
  differ from `address`.

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `address` | query | yes | string | House number and street, without town or postcode. |
| `locality` | query | no | string | City or town. |
| `region` | query | no | string | State, province or region. |
| `postcode` | query | no | string | Postal code. |
| `limit` | query | no | integer | Number of candidates to consider. `0`, the default, lets the server choose. At most one result is returned. |
| `layer` | query | no | Layer | Consider only candidates of this layer. An unknown layer returns `400`. |
| `country` | query | no | string | Return only results in these countries, as comma-separated ISO 3166-1 alpha-2 codes. A code that is not two letters returns `400`. A code the Pack does not cover returns no results. |

## Responses

- `200`: The best match, or no features when nothing matches.
- `400`: `address` is empty or too long, another field is too long, `limit` is too large, or a parameter is malformed.
- `405`: Method not allowed. The route accepts `GET` only.
- `500`: Internal server error.