# Nearby Mobility

Canonical URL: https://doc.roote.ai/capabilities/shared-mobility/nearby-mobility



Find shared mobility around GPS coordinates.

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

This endpoint searches shared-mobility stations and vehicles. It does not search railway stations, airports, public-transport lines, or generic POIs.

## Query parameters [#query-parameters]

| Parameter | Required | Default                     | Applied maximum | Description                      |
| --------- | -------- | --------------------------- | --------------- | -------------------------------- |
| `lat`     | Yes      | —                           | —               | Search-center latitude.          |
| `lon`     | Yes      | —                           | —               | Search-center longitude.         |
| `lng`     | No       | —                           | —               | Alternative alias for `lon`.     |
| `radius`  | No       | 400 m                       | 400 m           | Search radius in metres.         |
| `modes`   | No       | `bicycle,scooter,moped,car` | —               | Comma-separated mobility modes.  |
| `include` | No       | Both                        | —               | `stations`, `vehicles`, or both. |
| `limit`   | No       | 100                         | 100             | Page size.                       |
| `offset`  | No       | 0                           | —               | Pagination offset.               |
| `format`  | No       | `json`                      | —               | `json` or `geojson`.             |

```bash
curl "https://api.roote.ai/v1/nearby?lat=48.8566&lon=2.3522&radius=400&modes=bicycle,scooter&include=stations,vehicles" \\
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

## Response [#response]

```json
{
  "origin": { "lat": 48.8566, "lon": 2.3522 },
  "radius": 400,
  "modes": ["bicycle", "scooter"],
  "stations": [{
    "id": "station-id",
    "name": "Example station",
    "location": { "lat": 48.8570, "lon": 2.3518 },
    "distance_meters": 54,
    "availability": { "bicycles": 8, "free_docks": 12 },
    "freshness": { "updated_at": "2026-01-01T12:00:00Z", "valid": true }
  }],
  "vehicles": [{
    "id": "vehicle-id",
    "mode": "scooter",
    "location": { "lat": 48.8569, "lon": 2.3525 },
    "distance_meters": 41,
    "battery": 72,
    "rental_url": "https://provider.example/rent/vehicle-id"
  }],
  "places": [],
  "lines": [],
  "alerts": [],
  "meta": {
    "sources": [{ "id": "provider-id", "status": "ok" }],
    "realtime": true,
    "warnings": [],
    "total": 2,
    "limit": 100,
    "offset": 0,
    "requested_radius": 400,
    "applied_radius": 400,
    "requested_limit": 100,
    "applied_limit": 100,
    "coverage": "available"
  }
}
```

## Coverage [#coverage]

| Value       | Meaning                                  |
| ----------- | ---------------------------------------- |
| `available` | Matching results were found.             |
| `empty`     | Providers answered, but nothing matched. |
| `none`      | No provider covers the request.          |

<Callout title="Zero results are not zero coverage" type="info">
  Read `meta.coverage`, `meta.sources`, and `meta.warnings` before interpreting an empty result set.
</Callout>

HTTP 200 can still be returned when one provider fails and another succeeds.

## Processing model [#processing-model]

1. Select compatible providers.
2. Query adapters.
3. Normalize results.
4. Recalculate distance.
5. Enforce the applied radius.
6. Deduplicate stations.
7. Deduplicate vehicles.
8. Sort nearest to farthest.
9. Apply `offset` and `limit`.

Currently documented adapters include Fluctuo and CityBikes.