Introduction

This is the documentation of the OpenTransports API ! This document is for you if you want to build a server that will serve informations about transports in your area or if you want to build a new client.

Requirements

If you want to be added to the list of official servers and be available the users of the official OpenTransports web client you need to : - Make your code OpenSource - Support https - Pass the automatic tests (still under construction)

Endpoints

Agencies

Example

curl "https://server-url.com/agencies?latitude=48.86&longitude=2.35"

Response

[
    {
        "id": "FR/Paris/RATP",
        "name": "RATP",
        "url": "https://ratp.fr",
        "radius": 20000,
        "center": {
            "latitude": 48.856,
            "longitude": 2.35
        },
        "types": [
            {
                "id": 0,
                "name": "Tram",
                "icon": "https://server-url.com/medias/ferre/indices-ferres-2017.05/L_T"
            },
            ...
        ],
    }
]

Returns the list of supported agencies by the server. Each agencies contains informations about the kind of transports it supports.

HTTP Request

GET https://<server>/agencies

URL Parameters

Parameter	Default	Description
latitude/longitude	0	Return the agencies covering the position
radius	200	The search radius from the given position

Transports

Example

curl "https://server-url.com/transports?latitude=48.86&longitude=2.35&radius=200&realtime=true"

Response

[
    {
        "id": "3764645",
        "agencyID": "FR.Paris.RATP",
        "type": 3,
        "name": "LES HALLES - CENTRE GEORGES POMPIDOU",
        "line": "38",
        "position": {
            "latitude": 48.86069953105734,
            "longitude": 2.34956822574239
        },
        "informations": [
            {
                "title": "Montsouris",
                "content": ["2 mn", "3 mn"],
                "timestamp": 123456765
            }
        ],
        "iconURL": "https://server-url.com/medias/bus/indices/38genRVB.png"
    },
    ...
]

Get all transports by the server. This endpoint might need a position to prevent returning to much data. This comportment is the responsibility of the owner.

HTTP Request

GET https://<server>/transports

URL Parameters

Parameter	Default	Description
latitude/longitude	0	Return the transports around the position
radius	200	The search radius from the given position
realtime	false	Get the real-time data if possible

Transport

Example

curl "https://server-url.com/transports/3764645?realtime=true"

Response

{
    "ID": "3764645",
    "agencyID": "FR.Paris.RATP",
    "type": 3,
    "name": "LES HALLES - CENTRE GEORGES POMPIDOU",
    "line": "38",
    "position": {
        "latitude": 48.86069953105734,
        "longitude": 2.34956822574239
    },
    "passages": [],
    "iconURL": "https://server-url.com/medias/bus/indices/38genRVB.png"
}

Get the information of a transport using its ID

HTTP Request

GET https://<server>/transports/<transport-id>

URL Parameters

Parameter	Default	Description
realtime	false	Get the real-time data if possible

Data types

Agency

id     string // The unique identifier for the agency. Must be CountryCode/City/AgencyName
name   string // The name of the agency (Displayed)
url    string // The url to the agency website
radius int    // The radius covered by the agency
center {      // The central point of the agency
  latitude : float
  longitude: float
}
types [       // The types of transports supported by the agency
    {
        id   int    // The id of the type of the transports (See: Transports types)
        name string // A custom display name (Optional: Default to the generic ones)
        icon string // Generic icon (Optional: Default to the generic ones)
    }
]

Transport

id       string // Unique id of the transport (Used to retrieve information on the server)
agencyID string // The ID of the agency
type     int    // The type of transport (See: Transports Types)
name     string // The name of the transports (Displayed)
line     string // The line of the transports. (Optional: not necessary for Bikes or Cars)
iconURL  string // The url of an icon to display (Optional: will default to the generic icons from the agency)
position {      // The position of the transport
    latitude  float
    longitude float
}
informations [ // Information on the transports, either next passages or the amount of available bikes (Optional)
    {
        title     string   // The title of the content (Displayed)
        content   string[] // The content of the information (Displayed)
        warn      boolean  // If the content is a warning (Optional, Default: false)
        timestamp boolean  // When the information was retrieve (Optional: if not real-time, Default: 0)
    }
]

Transports Types

Tram      0
Metro     1
Rail      2
Bus       3
Ferry     4
Cable     5
Gondola   6
Funicular 7
Bike      8
Car       9
Unknown   10

Adapted from Google specification. Only difference is the presence of Bike and Car