# Geocode

Turn a place name or address into coordinates, with free text, structured or biased search.

`GET /v2/geocode`. Auth: API key or our website.

## Parameters

Send `q`, or at least one structured field, but never both.

| Parameter | Rule |
|---|---|
| `q` | Free text, up to 200 characters. |
| `street`, `house_number`, `city`, `county`, `state`, `postcode`, `country_code` | Structured search. `country_code` is two lowercase letters. |
| `limit` | 1 to 10, default 5. |
| `lang` | Two-letter code such as `en`. Without it, names come back in their local form. |
| `near` | `lng,lat`. Ranks results near this point. |
| `near_text` | An address or landmark to rank results near. Sending it with `near` is `400 invalid_request`. |
| `bbox` | `minLng,minLat,maxLng,maxLat`. Only returns results inside this box. |

`near` and `near_text` only change the ranking. `bbox` is the filter. For an app, use `near` when the user's location is on and `bbox` when it's off. See [Search near your user](../guides/search-near-user.md).

## Examples

```bash
# Free text
curl -s -H "X-API-Key: $QUADRUPER_KEY" \
  'https://quadruper.com/v2/geocode?q=SM%20City%20Iloilo&limit=3'

# Structured
curl -s -H "X-API-Key: $QUADRUPER_KEY" \
  'https://quadruper.com/v2/geocode?street=Benigno%20Aquino%20Avenue&city=Iloilo%20City&country_code=ph'

# Ranked near a named place
curl -s -H "X-API-Key: $QUADRUPER_KEY" \
  'https://quadruper.com/v2/geocode?q=SM%20City&near_text=Jaro%2C%20Iloilo%20City&limit=3'
```

This is an example response:

```json schema=geocode-response
{
  "results": [{
    "source": "osm",
    "id": "node/123456",
    "name": "SM City Iloilo",
    "label": "SM City Iloilo, Mandurriao, Iloilo City",
    "location": [122.5517, 10.7139],
    "category": "shop",
    "type": "mall",
    "address": { "street": "Benigno Aquino Avenue", "district": "Mandurriao", "city": "Iloilo City", "state": "Iloilo", "country": "Philippines", "country_code": "ph" }
  }],
  "reference": { "label": "Jaro, Iloilo City", "location": [122.563, 10.727] },
  "attribution": [{ "source": "osm", "text": "© OpenStreetMap contributors", "license": "ODbL-1.0" }]
}
```

## Response fields

| Field | Description |
|---|---|
| `results[].location` | `[lng, lat]`, the same order `POST /v2/route` takes. Use it unswapped. |
| `results[].id` | `node/<n>`, `way/<n>` or `relation/<n>`, or `null` when a result has no OpenStreetMap object. |
| `results[].name`, `category`, `type` | May be `null`. `category` is the OpenStreetMap key and `type` is its value. |
| `results[].address` | All keys are optional: `house_number`, `street`, `locality`, `district`, `city`, `county`, `state`, `postcode`, `country`, `country_code`. |
| `reference` | Only when you sent `near_text`. It's the place the text resolved to, so you can check it's the one you meant. |

No match is `200` with `"results": []`. If `near_text` finds nothing, the request fails with `422 reference_not_found` instead of running unranked.

See [Geocode an address, then route to it](../guides/geocode-then-route.md).