# Prevoz - Car Share Export API

A simple, read-only API to fetch **upcoming** car shares (rides).

## Endpoint

```
GET https://prevoz.org/api/carshare/export/
```

No authentication required.

## Query parameters

| Parameter       | Type              | Description                                                        |
|-----------------|-------------------|-------------------------------------------------------------------|
| `format`        | string            | `json` (recommended) or `jsonp`.                                  |
| `page`          | integer           | Page number (see Pagination below).                               |
| `updated_after` | string (ISO 8601) | Return only rides changed after this time. Use for incremental sync. |

## Pagination

Each request returns **one page** of results - there can be many pages
(e.g. ~1,600 upcoming rides = ~17 pages of 100). Walk through the pages with
`page` (or just follow the `next` URL) until `next` is `null`.

The response is a JSON object:

```json
{
  "page": 1,
  "count": 1667,
  "size": 100,
  "next": "https://prevoz.org/api/carshare/export/?page=2",
  "previous": null,
  "results": [ /* up to 100 rides */ ]
}
```

| Field      | Type        | Description                              |
|------------|-------------|------------------------------------------|
| `page`     | integer     | Current page number.                     |
| `count`    | integer     | **Total** rides across all pages.        |
| `size`     | integer     | Page size (100).                         |
| `next`     | string/null | URL of the next page (null if last).     |
| `previous` | string/null | URL of the previous page (null if first).|
| `results`  | array       | The rides on this page (see below).      |

## Ride fields (each item in `results`)

| Field                | Type              | Description                                                  |
|----------------------|-------------------|-------------------------------------------------------------|
| `id`                 | integer           | Ride id.                                                    |
| `from_geoname`       | string            | Departure city/place name (always present).                 |
| `from_geoname_lat`   | number            | Departure **city-centre** latitude (approximate).           |
| `from_geoname_long`  | number            | Departure **city-centre** longitude (approximate).          |
| `from_address`       | string/null       | Exact departure address if the user picked one, else null.  |
| `to_geoname`         | string            | Destination city/place name.                                |
| `to_geoname_lat`     | number            | Destination city-centre latitude (approximate).             |
| `to_geoname_long`    | number            | Destination city-centre longitude (approximate).            |
| `to_address`         | string/null       | Exact destination address if picked, else null.             |
| `transfer_timestamp` | string (ISO 8601) | Departure date and time.                                    |
| `price`              | number/null       | Price per seat in EUR (null if not set).                    |
| `num_people`         | integer           | Total seats offered.                                        |
| `free_places`        | integer           | Seats still available.                                      |
| `author`             | string            | Driver's first name.                                        |
| `author_rating`      | string            | Driver rating, e.g. `"4.6/5.0"`.                            |
| `link`               | string            | Link to the ride on prevoz.org.                             |
| `international`      | boolean           | True if the ride crosses a border.                          |
| `updated_at`         | string (ISO 8601) | When the ride was last changed.                             |
| `status`             | string            | `"active"` or `"inactive"`.                                 |

## Locations: exact address vs city

Every ride has location info at two levels of precision:

1. **Exact address (preferred):** `from_address` / `to_address` - the precise address
   the user picked. May be `null` if they only chose a city.
2. **City level (always present):** `from_geoname` + `from_geoname_lat` / `from_geoname_long`
   - the city centre (approximate, not the pick-up point).

**Rule of thumb:** if `*_address` is set, use it; otherwise use the city name + coordinates.
Coordinates for the exact address are not included - geocode the address string yourself
if you need precise lat/long.

## Examples

City-level ride (no exact address):

```json
{
  "id": 9780970,
  "from_geoname": "Ajdovščina", "from_address": null,
  "to_geoname": "Ljubljana", "to_address": null,
  "transfer_timestamp": "2026-06-22T06:35:00",
  "price": 5.0, "num_people": 3, "free_places": 3,
  "author": "Aleš", "author_rating": "0.0/5.0",
  "international": false, "status": "active"
}
```

Exact-address, international ride:

```json
{
  "id": 7954741,
  "from_geoname": "Ljubljana",
  "from_address": "Trg Osvobodilne fronte, 1000 Ljubljana",
  "to_geoname": "Mičevec",
  "to_address": "Zračna luka Franjo Tuđman - II. odvojak ulice Stjepana Radića, 10150 Grad Velika Gorica",
  "transfer_timestamp": "2026-06-30T15:15:00",
  "price": 14.0, "num_people": 5, "free_places": 0,
  "author": "Tadejlkk", "author_rating": "4.6/5.0",
  "international": true, "status": "active"
}
```

## Notes

- Only **upcoming** rides are returned (departure in the future).
- For syncing, remember the newest `updated_at` you've seen and pass it as
  `updated_after` next time to fetch only what changed.
- All text is UTF-8 (city and address names may contain characters like č, ž, đ).