# Geocode

Canonical URL: https://doc.roote.ai/capabilities/geography/geocode



Resolve an address or geographic expression into normalized geographic information and coordinates.

```http
GET https://api.roote.ai/v1/geocode
```

Typical intent: **Where exactly is this address?**

## Request [#request]

```bash
curl "https://api.roote.ai/v1/geocode?q=10%20rue%20de%20Rivoli%2C%20Paris" \\
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

| Parameter  | Required | Description                                                        |
| ---------- | -------- | ------------------------------------------------------------------ |
| `q`        | Yes      | Address or geographic expression, 1–200 characters after trimming. |
| `language` | No       | Preferred result language.                                         |
| `country`  | No       | Two-letter country code, normalized to uppercase.                  |
| `token`    | No       | Compatibility query token; prefer Bearer authentication.           |

## Response [#response]

Results are ordered by provider relevance. The first candidate is not a guaranteed unique match.

```json
{
  "results": [{
    "roote_id": null,
    "name": "10 Rue de Rivoli",
    "label": "10 Rue de Rivoli, 75004 Paris, France",
    "type": "address",
    "location": { "lat": 48.8557, "lon": 2.3570 },
    "address": {
      "formatted": "10 Rue de Rivoli, 75004 Paris, France",
      "street": "Rue de Rivoli",
      "street_number": "10",
      "city": "Paris",
      "postal_code": "75004",
      "region": "Île-de-France",
      "country": "France"
    },
    "source_id": "google",
    "source_place_id": "provider-place-id",
    "match_quality": "rooftop"
  }],
  "meta": { "source": "google", "cache": "miss", "total": 1, "query": "10 rue de Rivoli, Paris" }
}
```

No result is represented by HTTP 200 with an empty `results` array. Provider precision in `match_quality` is not a ROOTE confidence score.

## Limits and errors [#limits-and-errors]

The endpoint returns at most five ordered candidates. Documented failures include invalid input, rate limiting, provider unavailability, and provider timeouts. See [Errors](/roote-api/errors).