# Nearby Services

Canonical URL: https://doc.roote.ai/capabilities/urban-services/nearby-services



Find useful urban services around GPS coordinates.

```http
GET https://api.roote.ai/v1/services/nearby
```

## Query parameters [#query-parameters]

| Parameter | Required | Default | Maximum  | Description                                             |
| --------- | -------- | ------- | -------- | ------------------------------------------------------- |
| `lat`     | Yes      | —       | —        | Query-origin latitude.                                  |
| `lon`     | Yes      | —       | —        | Query-origin longitude.                                 |
| `types`   | Yes      | —       | —        | Comma-separated service types.                          |
| `country` | No       | —       | —        | Two-letter ISO country code.                            |
| `radius`  | No       | 1,500 m | 10,000 m | Search radius.                                          |
| `limit`   | No       | 50      | 200      | Aggregated result limit.                                |
| `debug`   | No       | `false` | —        | Provider and cache diagnostics.                         |
| `token`   | No       | —       | —        | Deprecated compatibility authentication; prefer Bearer. |

The aggregated endpoint currently has no `offset`, `format=geojson`, or `language` parameter.

## Response [#response]

```json
{
  "status": "success",
  "query_origin": { "lat": 48.8566, "lon": 2.3522 },
  "radius": 1500,
  "total": 3,
  "summary": { "parking": 1, "charging": 1, "toilets": 1 },
  "results": [{
    "id": "service-id",
    "type": "service",
    "service_type": "parking",
    "name": "Example parking",
    "location": { "lat": 48.8571, "lon": 2.3530 },
    "distance_meters": 78,
    "attributes": {},
    "provider": { "id": "google", "name": "Google" },
    "external_id": "provider-result-id",
    "source_id": "google",
    "source_type": "partner_api"
  }],
  "attributions": [{ "provider": "Google", "display_name": "Google", "required": true }]
}
```

Statuses are `success`, `empty`, and `partial`. The `summary` contains a counter for every requested type, including zero.

## Providers and limits [#providers-and-limits]

Documented providers may include `aedmap`, `refuge`, `openstreetmap`, `google`, and `inpost`. Google backs parking and charging with at most 20 results per category. InPost returns at most 100 lockers and availability is not guaranteed. The aggregate returns at most 200 results inside 10 km.

When a Google attribution has `required: true`, consuming applications must display it.

## Processing model [#processing-model]

1. Split the request by category.
2. Call associated providers.
3. Normalize results.
4. Filter to the applied radius.
5. Calculate distance from `query_origin`.
6. Merge results.
7. Build the summary.
8. Apply the global limit.

## Debug diagnostics [#debug-diagnostics]

`debug=true` can expose `providers`, `provider_calls`, `cache`, `requested_radius`, `applied_radius`, `requested_limit`, and `applied_limit`. Use it to diagnose provider unavailability, timeouts, authorization issues, and zero results.

See the [OpenAPI document](https://api.roote.ai/openapi.json).