# GTT Turin — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access GTT (Turin) public transport data including available service basins, line routes and stop lists, full-day timetables by route and date, stop search, and real-time arrivals with accessibility details.

**Category:** Maps & Geospatial | **Website:** [gtt.to.it/](https://gtt.to.it/) | **Docs:** [parse.bot/marketplace/a1455fd9-9a05-4d10-b184-c841ce520a35/gtt-to-it-api](https://parse.bot/marketplace/a1455fd9-9a05-4d10-b184-c841ce520a35/gtt-to-it-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-gtt-to-it-api-a1455fd9/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_all_schedules

Bulk extractor: for a given basin and day, fetch schedules for multiple lines paginated by start/limit. Each line includes all routes and, for each route, the stop list with all scheduled departures. Upstream response can be slow; keep limit low (1-3) for reliable results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `bacino` | string | No | Service basin code. |
| `giorno` | string | No | Service day in YYYYMMDD format. Omitting defaults to today's date. |
| `include_types` | string | No | Optional comma-separated vehicle types filter (e.g. Bus,Tram). If provided, only lines matching those types are returned. Values are case-insensitive and come from the tipo_mezzo field. |
| `limit` | integer | No | How many lines to process in this call. Lower values are more reliable due to upstream latency. |
| `start` | integer | No | 0-based start index into the line list. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-gtt-to-it-api-a1455fd9/get_all_schedules \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bacino":"<string>","giorno":"<string>","include_types":"<string>","limit":"<integer>","start":"<integer>"}'
```

### get_line_percorsi

Get a line's metadata and all available routes/variants (percorsi) including route codes, directions, stop lists, polylines, and service days. Upstream response times may vary (up to 60s for some lines). The percorsi array contains codice/verso pairs needed for get_percorso and get_percorso_schedule calls.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `bacino` | string | No | Service basin code. |
| `linea` | string | Yes | Line code (e.g. 3, 1068, METRO). Obtain from list_lines endpoint. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-gtt-to-it-api-a1455fd9/get_line_percorsi \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bacino":"<string>","linea":"<string>"}'
```

### get_percorso

Get detailed route geometry (polyline) and ordered stop list (fermate) for a specific route code and direction. The codice and verso must be a valid pair as returned by get_line_percorsi.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `bacino` | string | No | Service basin code. |
| `codice` | string | Yes | Route code (percorso code) from get_line_percorsi, e.g. 03A1, 03R2. |
| `linea` | string | Yes | Line code. |
| `verso` | string | Yes | Direction code matching the codice (e.g. As for andata, Di for discesa). Must be the verso paired with the given codice in get_line_percorsi output. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-gtt-to-it-api-a1455fd9/get_percorso \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bacino":"<string>","codice":"<string>","linea":"<string>","verso":"<string>"}'
```

### get_percorso_schedule

Get the full-day scheduled departure times at every stop for a specific line route and day. Returns an ordered stop list with all scheduled departures per stop. The codice and verso must be a valid pair from get_line_percorsi.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `bacino` | string | No | Service basin code. |
| `codice` | string | Yes | Route code (percorso code), e.g. 03A1. |
| `giorno` | string | No | Service day in YYYYMMDD format. Omitting defaults to today's date. |
| `linea` | string | Yes | Line code. |
| `verso` | string | Yes | Direction code (e.g. As, Di). Must match the codice from get_line_percorsi. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-gtt-to-it-api-a1455fd9/get_percorso_schedule \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bacino":"<string>","codice":"<string>","giorno":"<string>","linea":"<string>","verso":"<string>"}'
```

### get_stop_accessibility

Get richer stop data: upcoming arrivals with accessibility fields, plus nearby ticket resellers (rivendite) and accessible parking (stalli), configurable by flags. Arrivals include per-vehicle accessibility and tap-and-go status.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `bacino` | string | No | Service basin code. |
| `nminuti` | integer | No | Look-ahead window in minutes. |
| `order_by_line` | boolean | No | Whether to group/sort results by line. |
| `palina` | string | Yes | Stop code (palina). Obtain from search_stops endpoint. |
| `rivendite` | boolean | No | Include nearby ticket resellers. |
| `stalli` | boolean | No | Include nearby accessible parking stalls. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-gtt-to-it-api-a1455fd9/get_stop_accessibility \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bacino":"<string>","nminuti":"<integer>","order_by_line":"<boolean>","palina":"<string>","rivendite":"<boolean>","stalli":"<boolean>"}'
```

### get_stop_realtime

Get upcoming arrivals for a stop (palina). Returns stop metadata plus per-line arrival times (transiti) with real-time predictions when available. Real-time mode is recommended; scheduled-only mode (realtime=false) may have significantly slower response times.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `bacino` | string | No | Service basin code. |
| `palina` | string | Yes | Stop code (palina). Obtain from search_stops endpoint. |
| `realtime` | boolean | No | If true, prefer real-time predictions when available. Setting to false uses scheduled times only but may be significantly slower. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-gtt-to-it-api-a1455fd9/get_stop_realtime \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bacino":"<string>","palina":"<string>","realtime":"<boolean>"}'
```

### list_bacini

List service basins (bacini) available in the GTT schedule system. Each basin represents a transport service category: U (urban/suburban), E (extraurban), T (tourist), F (railway). No parameters required.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-gtt-to-it-api-a1455fd9/list_bacini \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### list_lines

List all transit lines for a given basin by parsing the GTT line listing pages. Returns line codes, labels, descriptions, and percorsi URLs. Use this to enumerate line codes before fetching schedules or route details.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `bacino` | string | No | Service basin code. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-gtt-to-it-api-a1455fd9/list_lines \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bacino":"<string>"}'
```

### search_stops

Autocomplete-style stop (palina) search by stop code or name fragment. Returns matching stops with their codes, names, basins, and localities. Use this to find stop codes for get_stop_realtime and get_stop_accessibility.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `term` | string | Yes | Search term (min 1 char). Can be a stop code or name fragment. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-gtt-to-it-api-a1455fd9/search_stops \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"term":"<string>"}'
```