NAV
shell

Getting started

Overview

navitia.io is the open API for building cool stuff with mobility data. It provides the following services

navitia is a HATEOAS API that returns JSON formated results, available at https://api.navitia.io

Have a look at the examples below to learn what services we provide and how to use them.

First step

Your token is available on your navitia.io account page.

It sounds like “3b036afe-0110-4202-b9ed-99718476c2e0”

Get a token here http://navitia.io/register/. We need your mail to stay in touch when Navitia changes.

Second step

# You can use curl to request Navitia
$ curl 'https://api.navitia.io/v1/'

Go to the API https://api.navitia.io

The simpliest way is to use a web browser. Our humble opinion is that firefox browser and a json viewer extension like JSONView is a good setup.

Third step

# In a curl way, with our fake token
$ curl 'https://api.navitia.io/v1/coverage/sandbox/' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

Use the token : if you use a modern web browser, you only have to paste it in the user name area, with no password.

Put token in Firefox browser

Or, in a simplier way, you can add your token in the address bar like :

See authentication section to find out more details on how to use your token when coding.

Then,

use the API ! The easiest is probably to jump to Examples below.

At some point you will want to read:

Try a basic request on Navitia playground

Try a journey request on Navitia playground

Try Navitia playgroung

Wrappers

To help you in the building of your project, there are some wrappers implemented (by Kisio or not) to query the API Navitia:

Language / Framework Plugin
PHP5 https://github.com/CanalTP/NavitiaComponent
Symfony 2 or 3 https://github.com/CanalTP/NavitiaBundle
Python https://github.com/leonardbinet/navitia_client
Python https://github.com/CanalTP/navitia_python_wrapper

About the data

The street network is extracted from OpenStreetMap. The public transport data are provided by networks that provide their timetables as open data. Some data improvements are achieved by Kisio Digital and are published back there https://navitia.opendatasoft.com.

Want to know if your city is in Navitia? Know if a special contributor is used? You can either search in datasets of the different coverages. Or use the filter provided on our data catalog https://navitia.opendatasoft.com.

Getting help

All available functions are documented in integration part

A mailing list is available to ask question: navitia@googlegroups.com

In order to report bug and make requests we created a github navitia project https://github.com/CanalTP/navitia/issues.

Stay tuned on twitter @navitia.

At last, we are present on IRC on the network Freenode, channel #navitia.

Some examples

This chapter shows some usages with the minimal required arguments. However, this is not a reference and not all APIs nor arguments are shown.

A quick exploration

$ curl 'https://api.navitia.io/v1/coverage' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'


HTTP/1.1 200 OK

{
    "start_production_date": "20140105",
    "status": "running",
    "shape": "POLYGON((-74.500997 40.344999,-74.500997 41.096999,-73.226 41.096999,-73.226 40.344999,-74.500997 40.344999))",
    "id": "sandbox",
    "end_production_date": "20140406"
}

navitia allows to dive into the public transport data.

To better understand how the API works let’s ask the API the different main possibilities by simply querying the API endpoint: https://api.navitia.io/v1/

The links section of the answer contains the different possible interactions with the API.

As you can see there are several possibilities like for example coverage to navigate through the covered regions data or journeys to compute a journey.

Now let’s see what interactions are possible with coverage:

This request will give you:

$ curl 'https://api.navitia.io/v1/coverage/sandbox/lines' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'


HTTP/1.1 200 OK

{
    "lines":[
        {
            "id":"line:RAT:M1",
            "code":"1",
            "name":"Château de Vincennes - La Défense",
            "opening_time":"053000",
            "closing_time":"013600",
            "color":"F2C931",
            "commercial_mode":{
                "id":"commercial_mode:Metro",
                "name":"Metro"
            },
            "physical_modes":[
                {
                    "id":"physical_mode:Metro",
                    "name":"Métro"
                }
            ],
            "network":{
                "id":"network:RAT:1",
                "name":"RATP"
            },
            "routes":[
                {
                    "id":"route:RAT:M1",
                    "name":"Château de Vincennes - La Défense",
                    "direction":{
                        "id":"stop_area:RAT:SA:DENFE",
                        "name":"La Défense Grande Arche (Puteaux)"
                    }
                },
                {
                    "id":"route:RAT:M12_R",
                    "name":"Mairie d'Issy - Front Populaire",
                    "direction":{
                        "id":"stop_area:RAT:SA:MISSY",
                        "name":"Mairie d'Issy (Vanves)"
                    }
                }
            ]
        }
    ]
}

In the links section there is for example this link: "href": "https://api.navitia.io/v1/coverage/{regions.id}/lines"

This link is about lines (according to its rel attribute) and is templated which means that it needs additional parameters.
The parameters are identified with the { } syntax. In this case it needs a region id. This id can be found in the regions section.

To query for the public transport lines of New York we thus have to call: https://api.navitia.io/v1/coverage/us-ny/lines

Easy isn’t it?

Code it yourself on JSFiddle

We could push the exploration further and:

What places have a name that start with ‘eiff’

The /places API finds any object whose name matches the first letters of the query.

To find the objects that start with “tran” the request should be: https://api.navitia.io/v1/coverage/fr-idf/places?q=eiff

This API is fast enough to use it for autocompleting a user request.

What places are within 1000 meters

The /places_nearby API finds any object within a certain radius as a crow flies. This API is not accessible from the main endpoint but has to be applied on a stop point, an address, some coordinates,…

All objects around the coordinates of the Transamerica Pyramid can be fetched with the following request: https://api.navitia.io/v1/coverage/us-ca/coords/-122.402770;37.794682/places_nearby

We could, in the same fashion, ask for the objects around a particuliar stop area (stop_area:OSF:SA:CTP4025 for example): https://api.navitia.io/v1/coverage/us-ca/stop_areas/stop_area:OSF:SA:CTP4025/places_nearby

Optionally you can select what object types to return and change the radius.

About itinerary

A simple route computation

Let’s find out how to get from the view point of the Golden Gate bridge to the Transamerica Pyramid in San Francisco. We need to use the journeys API.

The coordinates of the view point are longitude = -122.4752, latitude = 37.80826 and the coordinates of the Transamercia Pyramid are longitude = -122.402770, latitude = 37.794682. The coordinates are always in decimal degrees as WGS84 (also known as GPS coordinates). The coordinates are given to the API with the following format: longitute;latitude.

The arguments are the following:

This API has more options explained in the reference as:

What stations can be reached in the next 20 minutes

The API can computes all the reachable stop points from an origin within a given maximum travel duration. That’s what we call an isochron (see journeys section )

All the stop points that can be reached from the Transamerica Pyramid can be fetched with the following request: https://api.navitia.io/v1/coverage/us-ca/coords/-122.402770;37.794682/journeys?max_duration=1200

It returns for each destination stop point the earliest arrival and a link to the journey detail.

Authentication

3 ways to request Navitia


#using "headers"
$ curl 'https://api.navitia.io/v1/coverage' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0' 

#using "users": don't forget ":" at the end of line !
$ curl https://api.navitia.io/v1/coverage -u 3b036afe-0110-4202-b9ed-99718476c2e0:

#using "straight URL"
$ curl https://3b036afe-0110-4202-b9ed-99718476c2e0@api.navitia.io/v1/coverage

Authentication is required to use navitia.io. When you register we will give you an authentication key that must accompany each API call you make.

Navitia.io uses Basic HTTP authentication for authentication, where the username is the key, and password remains empty.

For example, in a Curl way, you can request either :

curl 'https://api.navitia.io/v1/coverage' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

or

curl https://api.navitia.io/v1/coverage -u 3b036afe-0110-4202-b9ed-99718476c2e0:

(don’t forget : after the key)

or

curl https://3b036afe-0110-4202-b9ed-99718476c2e0@api.navitia.io/v1/coverage

Journey planningJourney planning

Try it on Navitia playground

The multi-modal itinerary feature allows you to compute the best routes from point A to point B using all available means of travel, including: bus, train, subway, bike, public bike, walking, car, etc. This function returns a roadmap with specific instructions for a route based on available information, such as: time of departure and arrival, journey time, possible modes of transport, and walking distance.

a journey on Navitia playground

In order to compute a journey, you may have to use these APIs (click on them for details):

DeparturesNext departures and arrivals

The “Next Departures” feature provides the next scheduled departures or arrivals for a specific mode of public transport (bus, tram, metro, train) at your selected stop, near coordinates, etc.

Try it on Navitia playground (click on “EXT” buttons to see times)

Try it on Navitia playground

In order to display departures, you may have to use these APIs (click on them for details):

TimetablesTimetables

The Timetables features gives you access to line schedules on public transport, allowing you to find the times public transport is expected at specific stops.

It returns a variety of differents informations, including: stop points in right order, times, accessibility informations, vehicle informations, etc.

In order to display line schedules, you may have to use these APIs (click on them for details):

Places nearbyPlaces nearby

Try it on Navitia playground (click on “MAP” buttons to see places)

The Places Nearby feature displays the different transport options around a location - a GPS coordinate, or an address, for example.

a map around on Navitia playground

Using OpenStreetMap data, this function also provides information about bicycle parking, public park schedules, and parking fees.

You can use these APIs (click on them for details):

Explore transportExplore transport

Try it on Navitia playground

The Explore Transport feature lets you explore places, coordinates, bus stops, subway stations, etc. to navigate all the data available on the API (collection service).

some data request on Navitia playground

You can use these APIs (click on them for details):

IsochronesIsochrones

Try it on Navitia playground (click on “MAP” buttons for “wow effect”)

Whether using a specific set of coordinates or a general location, you can find places within your reach and their corresponding travel times, using a variety of transportation options. You can even specify the maximum amount of time you want to spare on travel and find the quickest way to reach your destination.

a simple isochrone request on Navitia playground

Isochrone computing exposes information under two formats:

Code it yourself on JSFiddle

Code it yourself on JSFiddle

You can use these APIs (click on them for details):

interface

The base URL for navitia.io is : https://api.navitia.io/v1/

We aim to implement HATEOAS concept with Navitia.

Every resource returns a response containing a links object, a paging object, and the requested objects, following hypermedia principles. That’s lots of links. Links allow you to know all accessible uris and services for a given point.

Paging

Every Navitia response contains a paging object

Key Type Description
items_per_page int Number of items per page
items_on_page int Number of items on this page
start_page int The page number
total_result int Total number of items for this request

You can navigate through a response using 2 parameters

Parameter Type Description
start_page int The page number
count int Number of items per page

Templated URL

From every object collection

#first request

$ curl 'https://api.navitia.io/v1/coverage/sandbox/lines' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

#response
HTTP/1.1 200 OK

#first line is like:

{
    "lines": [
        {
            "id": "line:RAT:M1",
            "code": "1",
            "name": "Château de Vincennes - La Défense",
            "...": "..."
        },
        {...}
        ],
    ...,

#and a templated link from the example above:

    "links": [
        {
            "href": "https://api.navitia.io/v1/coverage/sandbox/lines/{lines.id}/stop_schedules",
            "rel": "stop_schedules",
            "templated": true
        },
        {...}
    ]
}

#you can then request for "stop_schedules" service using templating
#be careful, without any filter, the response can be huge

#second request
#{line.id} has to be replaced by "line:RAT:M1"
$ curl 'https://api.navitia.io/v1/coverage/sandbox/lines/line:RAT:M1/stop_schedules' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

#here is a smarter request for a line AND a stop_area
$ curl 'https://api.navitia.io/v1/coverage/sandbox/lines/line:RAT:M1/stop_areas/stop_area:RAT:SA:PLROY/stop_schedules' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

Under some link sections, you will find a “templated” property.

If “templated” is true, then you will have to format the link with your right id as describe in the example. In order to do that, you will have to

Inner references

#You may find "disruptions" link, as

{
    "internal": true,
    "type": "disruption",
    "id": "edc46f3a-ad3d-11e4-a5e1-005056a44da2",
    "rel": "disruptions",
    "templated": false
}

Some link sections holds disruption links. These links are templated.

That means :

Objects order

Unless specified, objects lists are not sorted and stability of objects’ order is not guaranteed.

Examples of sorted objects tables:

Examples of unsorted responses:

Lifetime of id

The way id (or uri) of an object is generated is not garanteed stable, nor are the data processed. So we advise to limit to the minimum storing ids/uris of objects. We recommend to use as much as possible a previous call to Places and PT_objects. Also, be resilient if one of those ids/uris disappears.

API catalog

Coverage

Also known as /coverage service.

You can easily navigate through regions covered by navitia.io, with the coverage api. The shape of the region is provided in GeoJSON.

In Navitia, a coverage is a combination of multiple datasets provided by different contributors (typically data provided by a transport authority in GTFS format). The combination of datasets used by a coverage is arbitrarily determined but we try to use something that makes sense and has a reasonnable amount of data (country).

The only arguments are the ones of paging.

Accesses

url Result
coverage List of the areas covered by navitia
coverage/{region_id} Information about a specific region
coverage/{lon;lat} Information about a specific region

Datasets

Very simple endpoint providing the sets of data that are used in the given coverage.

Those datasets (typically from transport authority in GTFS format), each provided by a unique contributor are forming a coverage.

Contributor providing the dataset is also provided in the response. Very usefull to know all the datas that form a coverage.

The only arguments are the ones of paging.

Accesses

url Result
`coverage/{region_id}/datasets List of the datasets of a specific region
`coverage/{region_id}/datasets/{dataset_id} Information about a specific dataset

Contributors

Very simple endpoint providing the contributors of data for the given coverage.

A contributor is a data provider (typically a transport authority), and can provide multiple datasets. For example, the contributor Italian Railways will provide a dataset for the national train and some others for the regional trains. We will try to put them in the same coverage so that we assemble them in the same journey search, using both.

Very usefull to know which contributors are used in the datasets forming a coverage.

The only arguments are the ones of paging.

Accesses

url Result
`coverage/{region_id}/contributors List of the contributors of a specific region
`coverage/{region_id}/contributors/{dataset_id} Information about a specific contributor

Inverted geocoding

#request
$ curl 'https://api.navitia.io/v1/coords/2.37705;48.84675' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

#response where you can find the right Navitia coverage, and a useful label
HTTP/1.1 200 OK

{
    "regions": [
        "sandbox"
    ],
    "address": {
        "id": "2.37705;48.84675",
        "label": "20 Rue Hector Malot (Paris)",
        "...": "..."
    }
}

in this example, the coverage id is “regions”: [“sandbox”] so you can ask Navitia on accessible local mobility services:

#request
$ curl 'https://api.navitia.io/v1/coverage/sandbox' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

#response
HTTP/1.1 200 OK

{
    "regions": [{
        "status": "running",
        "start_production_date": "20160101","end_production_date": "20160831",
        "id": "sandbox"
    }],
    "links": [
        {"href": "https://api.navitia.io/v1/coverage/sandbox/coords"},
        {"href": "https://api.navitia.io/v1/coverage/sandbox/places"},
        {"href": "https://api.navitia.io/v1/coverage/sandbox/networks"},
        {"href": "https://api.navitia.io/v1/coverage/sandbox/physical_modes"},
        {"href": "https://api.navitia.io/v1/coverage/sandbox/companies"},
        {"href": "https://api.navitia.io/v1/coverage/sandbox/commercial_modes"},
        {"href": "https://api.navitia.io/v1/coverage/sandbox/lines"},
        {"href": "https://api.navitia.io/v1/coverage/sandbox/routes"},
        {"href": "https://api.navitia.io/v1/coverage/sandbox/stop_areas"},
        {"href": "https://api.navitia.io/v1/coverage/sandbox/stop_points"},
        {"href": "https://api.navitia.io/v1/coverage/sandbox/line_groups"},
        {"href": "https://api.navitia.io/v1/coverage/sandbox/connections"},
        {"href": "https://api.navitia.io/v1/coverage/sandbox/vehicle_journeys"},
        {"href": "https://api.navitia.io/v1/coverage/sandbox/poi_types"},
        {"href": "https://api.navitia.io/v1/coverage/sandbox/pois"},
        {"href": "https://api.navitia.io/v1/coverage/sandbox/disruptions"},
        {"href": "https://api.navitia.io/v1/coverage/sandbox/datasets"},
        {"href": "https://api.navitia.io/v1/coverage/sandbox/line_groups"},
        {"href": "https://api.navitia.io/v1/coverage/sandbox/trips"},
        {"href": "https://api.navitia.io/v1/coverage/sandbox/"}
    ]
}

Also known as /coords service.

Very simple service: you give Navitia some coordinates, it answers you

Accesses

url Result
coords/{lon;lat} Detailed address point
coverage/{region_id}/coords/{lon;lat} Detailed address point

You can also combine /coords with other filter as :

Public Transportation Objects exploration

Try it on Navitia playground

curl 'https://api.navitia.io/v1/coverage/sandbox/pt_objects?q=metro%201' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

HTTP/1.1 200 OK

{
    "pt_objects":[
        {
            "id":"line:RAT:M1",
            "name":"RATP Metro 1 (Château de Vincennes - La Défense)",
            "embedded_type":"line",
            "line":{
                "id":"line:RAT:M1",
                "name":"Château de Vincennes - La Défense",
                "code":"1",
                "...": "..."
            }
        },
        {
            "id":"line:RAT:M11",
            "name":"RATP Metro 11 (Mairie des Lilas - Châtelet)"
            "embedded_type":"line",
            "line":{
                "...": "..."
            },
        },
        {
            "id":"line:RAT:M12",
            "name":"RATP Metro 12 (Mairie d'Issy - Front Populaire)",
            "embedded_type":"line",
            "line":{
                "...": "..."
            }
        },
        {"...": "..."},
        {"...": "..."}
    ]
}

Also known as /networks, /lines, /stop_areas… services.

Once you have selected a region, you can explore the public transportation objects easily with these APIs. You just need to add at the end of your URL a collection name to see every objects within a particular collection. To see an object detail, add the id of this object at the end of the collection’s URL. The paging arguments may be used to paginate results.

Accesses

url Result
/coverage/{region_id}/{collection_name} Collection of objects of a region
/coverage/{region_id}/{collection_name}/{object_id} Information about a specific region
/coverage/{lon;lat}/{collection_name} Collection of objects of a region
/coverage/{lon;lat}/{collection_name}/{object_id} Information about a specific region

Collections

Parameters

depth

This tiny parameter can expand Navitia power by making it more wordy. Here is some examples around “metro line 1” from the Parisian network:

odt level

It allows you to request navitia for specific pickup lines. It refers to the odt section. “odt_level” can take one of these values:

For example

https://api.navitia.io/v1/coverage/fr-nw/networks/network:lila/lines

https://api.navitia.io/v1/coverage/fr-nw/networks/network:Lignes18/lines?odt_level=scheduled

distance

If you specify coords in your filter, you can modify the radius used for the proximity search.

https://api.navitia.io/v1/coverage/fr-idf/coords/2.377310;48.847002/stop_schedules?distance=500

headsign

If given, add a filter on the vehicle journeys that has the given value as headsign (on vehicle journey itself or at a stop time).

Examples:

since / until

To be used only on “vehicle_journeys” and “disruptions” collection, to filter on a period. Both parameters “until” and “since” are optional.

Example:

disable_geojson

By default geojson part of an object are returned in navitia’s responses, this parameter allows you to remove them, it’s useful when searching lines that you don’t want to display on a map.

Examples :

Filter

It is possible to apply a filter to the returned collection, using “filter” parameter. If no object matches the filter, a “bad_filter” error is sent. If filter can not be parsed, an “unable_to_parse” error is sent. If object or attribute provided is not handled, the filter is ignored.

{collection}.has_code

Try it on Navitia playground

#for any pt_object request, as this one:
$ curl 'https://api.navitia.io/v1/coverage/sandbox/stop_areas' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

#you can find codes on every pt_object, like:
HTTP/1.1 200 OK

{
    "stop_areas": [
        {
            "codes" :[
                {
                    "type": "external_code",
                    "value": "RATCAMPO"
                },
                {
                    "type" : "source",
                    "value" : "CAMPO"
                }
            ]
            "...": "...",
        },
        {...}
]

#you can request for objects with a specific code
#for example, you can get this stoparea, having a "source" code "CAMPO"
#by using parameter "filter=stop_area.has_code(source,CAMPO)" like:

$ curl 'https://api.navitia.io/v1/coverage/sandbox/stop_areas?filter=stop_area.has_code(source,CAMPO)' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

Every object managed by Navitia comes with its own list of ids. You will find some source ids, merge ids, etc. in “codes” list in json responses. Be careful, these codes may not be unique. The navitia id is the only unique id.

You may have to request an object by one of these ids, in order to call an external service for example.

The filter format is filter={collection_name}.has_code({code_type},{code_value})

Examples :

line.code

It allows you to request navitia objects referencing a line whose code is the one provided, especially lines themselves and routes.

Examples :

Few exploration examples

#request
$ curl 'https://api.navitia.io/v1/coverage/sandbox/physical_modes' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

#response
HTTP/1.1 200 OK

{
    "links": [
        "..."
    ],
    "pagination": {
        "..."
    },
    "physical_modes": [
        {
            "id": "physical_mode:Bus",
            "name": "Bus"
        },
        {
            "id": "physical_mode:Metro",
            "name": "Métro"
        },
        "..."
    ]
}

Other examples

You will find lots of more advanced example in a quick exploration chapter

Autocomplete on Public Transport objects

Try it on Navitia playground

# Search objects of type 'line' or 'route' containing 'metro 4'

#request
$ curl 'https://api.navitia.io/v1/coverage/sandbox/pt_objects?q=metro%204&type\[\]=line&type\[\]=route' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

#response
HTTP/1.1 200 OK

{
    "pt_objects": [
        {
            "embedded_type": "line",
            "line": {...},
            "id": "line:RAT:M4",
            "name": "RATP Metro 4 (Porte de Clignancourt - Mairie de Montrouge)"
        },
    ],
    "links" : [...],
}

Also known as /pt_objects service.

This endpoint allows you to search in public transport objects using their names. It’s a kind of magical autocomplete on public transport data. It returns a collection of pt_object.

How does it works

Differents kind of objects can be returned (sorted as):

Here is a typical use case. A traveler has to find a line between the 1500 lines around Paris. For example, he could key without any filters:

traveler input: “bob”

  • network : “bobby network”
  • line : “bobby bus 1”
  • line : “bobby bus 2”
  • route : “bobby bus 1 to green”
  • route : “bobby bus 1 to rose”
  • route : “bobby bus 2 to yellow”
  • stop_area : “…

traveler input: "bobby met”

  • line : “bobby metro 1”
  • line : “bobby metro 11”
  • line : “bobby metro 2”
  • line : “bobby metro 3”
  • route : “bobby metro 1 to Martin”
  • route : “bobby metro 1 to Mahatma”
  • route : “bobby metro 11 to Marcus”
  • route : “bobby metro 11 to Steven”
  • route : “…

traveler input: "bobby met 11” or “bobby metro 11”

  • line : “bobby metro 11”
  • route : “bobby metro 11 to Marcus”
  • route : “bobby metro 11 to Steven”

Access

# Search objects of type 'network' containing 'RAT'
curl 'https://api.navitia.io/v1/coverage/sandbox/pt_objects?q=RAT&type\[\]=network' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

HTTP/1.1 200 OK

{
    "pt_objects":[
        {
            "id":"network:RAT:1",
            "name":"RATP",
            "embedded_type":"network",
            "network":{
                "id":"network:RAT:1",
                "name":"RATP"
            }
        }
    ]
}
url Result
/coverage/{region_id}/{resource_path}/pt_objects List of public transport objects

Parameters

Required Name Type Description Default value
yep q string The search term
nop type[] array of string Type of objects you want to query It takes one the following values: [network, commercial_mode, line, route, stop_area] [network, commercial_mode, line, route, stop_area]

Autocomplete on geographical objects

#request
$ curl 'https://api.navitia.io/v1/coverage/sandbox/places?q=rue' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

#response
HTTP/1.1 200 OK

{
    "places": [
        {
        "embedded_type": "stop_area",
        "stop_area": {...},
        "id": "stop_area:RAT:SA:RDBAC",
        "name": "Rue du Bac (Paris)"
        },
        ...
    ],
    "links" : [...],
}

Also known as /places service.

This endpoint allows you to search in all geographical objects using their names, returning a place collection.

It is very useful to make some autocomplete stuff ie to understand the user input even if he has mittens.

Differents kind of objects can be returned (sorted as):

Access

url Result
/coverage/{region_id}/places List of geographical objects within a coverage
/places Beta: List of geographical objects within Earth

Parameters

Required Name Type Description Default value
yep q string The search term
nop type[] array of string Type of objects you want to query It takes one the following values: [stop_area, address, administrative_region, poi, stop_point] [stop_area, address, poi, administrative_region]
nop admin_uri[] array of string If filled, it will filter the search within the given admin uris
nop disable_geojson boolean remove geojson from the response False
nop from string Coordinates longitude;latitude used to prioritize the objects around this coordinate. Note this parameter will be taken into account only if the autocomplete’s backend can handle it

Places Nearby

Try it on Navitia playground (click on “MAP” buttons to see places)

#request
$ curl 'https://api.navitia.io/v1/coverage/sandbox/stop_areas/stop_area:RAT:SA:CAMPO/places_nearby' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

#response
HTTP/1.1 200 OK

{
"places_nearby": [
    {
        "embedded_type": "stop_point",
        "stop_point": {...},
        "distance": "0",
        "quality": 0,
        "id": "stop_point:RAT:SP:CAMPO2",
        "name": "Campo-Formio (Paris)"
    },
    ....
}

Also known as /places_nearby service.

This endpoint allowe you to search for public transport objects that are near another object, or nearby coordinates, returning a places collection.

Accesses

url Result
/coord/{lon;lat}/places_nearby List of objects near the resource without any region id
/coverage/{lon;lat}/coords/{lon;lat}/places_nearby List of objects near the resource without any region id
/coverage/{region_id}/coords/{lon;lat}/places_nearby List of objects near a coordinate
/coverage/{region_id}/{resource_path}/places_nearby List of objects near the resource

Parameters

Required name Type Description Default value
nop distance int Distance range in meters 500
nop type[] array of string Type of objects you want to query [stop_area, stop_point, poi, administrative_region]
nop admin_uri[] array of string If filled, will filter the search within the given admin uris
nop filter string Use to filter returned objects. for example: places_type.id=theater
nop disable_geojson boolean remove geojson from the response False

Filters can be added:

Journeys

Try it on Navitia playground

#request
$ curl 'https://api.navitia.io/v1/coverage/sandbox/journeys?from=2.3749036;48.8467927&to=2.2922926;48.8583736' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'
#response
HTTP/1.1 200 OK

{
    "tickets": [],
    "links": [...],
    "journeys": [
    {
        "fare": {...},
        "status": "",
        "tags": [],
        "type": "comfort",
        "nb_transfers": 0,
        "duration": 2671,
        "requested_date_time": "20160613T133748",
        "departure_date_time": "20160613T133830",
        "arrival_date_time": "20160613T142301",
        "calendars": [...],
        "co2_emission": {"unit": "gEC", "value": 24.642},
        "sections": [
        {
            "from": {... , "name": "Rue Abel"},
            "to": {... , "name": "Bercy (Paris)"},
            "arrival_date_time": "20160613T135400",
            "departure_date_time": "20160613T133830",
            "duration": 930,
            "type": "street_network",
            "mode": "walking",
            "geojson": {...},
            "path": [...],
            "links": []
        },{
            "from": {... , "name": "Bercy (Paris)"},
            "to": {... , "name": "Bir-Hakeim Tour Eiffel (Paris)"},
            "type": "public_transport",
            "display_informations": {
                "direction": "Charles de Gaulle — Étoile (Paris)",
                "code": "6",
                "color": "79BB92",
                "physical_mode": "M?tro",
                "headsign": "Charles de Gaulle Etoile",
                "commercial_mode": "Metro",
                "label": "6",
                "text_color": "000000",
                "network": "RATP"},
            "departure_date_time": "20160613T135400",
            "arrival_date_time": "20160613T141500",
            "base_arrival_date_time": "20160613T141500",
            "base_departure_date_time": "20160613T135400",
            "duration": 1260,
            "additional_informations": ["regular"],
            "co2_emission": {"unit": "gEC", "value": 24.642},
            "geojson": {...},
            "stop_date_times": [
            {
                "stop_point": {... , "label": "Bercy (Paris)"},
                "arrival_date_time": "20160613T135400",
                "departure_date_time": "20160613T135400",
                "base_arrival_date_time": "20160613T135400",
                "base_departure_date_time": "20160613T135400"
            },
            {...}
            ]
        },
        {
            "from": {... , "name": "Bir-Hakeim Tour Eiffel (Paris)" },
            "to": {... , "name": "Allée des Refuzniks"},
            "arrival_date_time": "20160613T142301",
            "departure_date_time": "20160613T141500",
            "duration": 481,
            "type": "street_network",
            "mode": "walking",
            "geojson": {...},
            "path": [...],
        }]
    },
    {...},
    {...}],
    "disruptions": [],
    "notes": [],
    "feed_publishers": [
    {
        "url": "",
        "id": "sandbox",
        "license": "",
        "name": ""
    }],
    "exceptions": []
}

Also known as /journeys service. This api computes journeys or isochrone tables.

There are two ways to access to this service : journeys from point to point, or isochrones from a single point to every point.

Accesses

url Result
/journeys List of journeys from wherever land
/coverage/{region_id}/journeys List of journeys on a specific coverage
/coverage/{a_path_to_resource}/journeys Isochrone from a specific coverage

Requesting a single journey

The most used way to access to this service is to get the /journeys api endpoint. Here is the structure of a standard journey request:

https://api.navitia.io/v1/journeys?from={resource_id_1}&to={resource_id_2}&datetime={date_time_to_leave} .

Code it yourself on JSFiddle

In the examples, positions are given by coordinates and no network is specified. However when no coordinates are provided, you need to provide on what region you want to request as https://api.navitia.io/v1/coverage/us-ca/journeys?from=-122.4752;37.80826&to=-122.402770;37.794682

The list of regions covered by navitia is available through coverage.

Requesting an isochrone

If you want to retreive every possible journey from a single point at a time, you can request as follow:

https://api.navitia.io/v1/{a_path_to_resource}/journeys

It will retrieve all the journeys from the resource (in order to make isochrone tables).

Code it yourself on JSFiddle

The isochrones service exposes another response structure, which is simpler, for the same data.

Main parameters

Required Name Type Description Default value
nop from id The id of the departure of your journey. If none are provided an isochrone is computed
nop to id The id of the arrival of your journey. If none are provided an isochrone is computed
nop datetime iso-date-time Date and time to go now
nop datetime_represents string Can be departure or arrival.
If departure, the request will retrieve journeys starting after datetime.
If arrival it will retrieve journeys arriving before datetime.
departure
nop traveler_type enum Define speeds and accessibility values for different kind of people.
Each profile also automatically determines appropriate first and last section modes to the covered area. Note: this means that you might get car, bike, etc fallback routes even if you set forbidden_uris[]! You can overload all parameters (especially speeds, distances, first and last modes) by setting all of them specifically. We advise that you don’t rely on the traveler_type’s fallback modes (first_section_mode[] and last_section_mode[]) and set them yourself.

enum values:

  • standard
  • slow_walker
  • fast_walker
  • luggage
  • wheelchair
standard
nop data_freshness enum Define the freshness of data to use to compute journeys
  • realtime
  • base_schedule
when using the following parameter “&data_freshness=base_schedule”
you can get disrupted journeys in the response. You can then display the disruption message to the traveler and make a realtime request to get a new undisrupted solution.
base_schedule
nop forbidden_uris[] id If you want to avoid lines, modes, networks, etc.
Note: the forbidden_uris[] concern only the public transport objects. You can’t for example forbid the use of the bike with them, you have to set the fallback modes for this (first_section_mode[] and last_section_mode[])
nop first_section_mode[] array of string Force the first section mode if the first section is not a public transport one. It takes one the following values: walking, car, bike, bss.
bss stands for bike sharing system.
It’s an array, you can give multiple modes.

Note: choosing bss implicitly allows the walking mode since you might have to walk to the bss station.
Note 2: The parameter is inclusive, not exclusive, so if you want to forbid a mode, you need to add all the other modes.
Eg: If you never want to use a car, you need: first_section_mode[]=walking&first_section_mode[]=bss&first_section_mode[]=bike&last_section_mode[]=walking&last_section_mode[]=bss&last_section_mode[]=bike
walking
nop last_section_mode[] array of string Same as first_section_mode but for the last section walking

Other parameters

Required Name Type Description Default value
nop max_duration_to_pt int Maximum allowed duration to reach the public transport.
Use this to limit the walking/biking part.
Unit is seconds
15*60 s
nop walking_speed float Walking speed for the fallback sections
Speed unit must be in meter/seconds
1.12 m/s
(4 km/h)
Yes, man, they got the metric system
nop bike_speed float Biking speed for the fallback
Speed unit must be in meter/seconds
4.1 m/s
(14.7 km/h)
nop bss_speed float Speed while using a bike from a bike sharing system for the fallback sections
Speed unit must be in meter/seconds
4.1 m/s
(14.7 km/h)
nop car_speed float Driving speed for the fallback sections
Speed unit must be in meter/seconds
16.8 m/s
(60 km/h)
nop min_nb_journeys int Minimum number of different suggested journeys
More in multiple_journeys
nop max_nb_journeys int Maximum number of different suggested journeys
More in multiple_journeys
nop count int Fixed number of different journeys
More in multiple_journeys
nop max_nb_tranfers int Maximum number of transfers in each journey 10
nop max_duration int Maximum duration of journeys in secondes. Really useful when computing an isochrone 10
nop disruption_active boolean For compatibility use only.
If true the algorithm take the disruptions into account, and thus avoid disrupted public transport.
Rq: disruption_active=true = data_freshness=realtime
Use data_freshness parameter instead
False
nop wheelchair boolean If true the traveler is considered to be using a wheelchair, thus only accessible public transport are used
be warned: many data are currently too faint to provide acceptable answers with this parameter on
False
nop debug boolean Debug mode
No journeys are filtered in this mode
False

Objects

Here is a typical journey, all sections are detailed below

image

Main response

Field Type Description
journeys array of journeys List of computed journeys
links link Links related to the journeys

Journey

Field Type Description
duration int Duration of the journey
nb_transfers int Number of transfers in the journey
departure_date_time iso-date-time Departure date and time of the journey
requested_date_time iso-date-time Requested date and time of the journey
arrival_date_time iso-date-time Arrival date and time of the journey
sections array of section All the sections of the journey
from places The place from where the journey starts
to places The place from where the journey ends
links link Links related to this journey
type enum string Used to qualify a journey. See the journey-qualification section for more information
fare fare Fare of the journey (tickets and price)
tags array of string List of tags on the journey. The tags add additional information on the journey beside the journey type. See for example multiple_journeys.
status enum Status from the whole journey taking into acount the most disturbing information retrieved on every object used. Can be:
  • NO_SERVICE
  • REDUCED_SERVICE
  • SIGNIFICANT_DELAYS
  • DETOUR
  • ADDITIONAL_SERVICE
  • MODIFIED_SERVICE
  • OTHER_EFFECT
  • UNKNOWN_EFFECT
  • STOP_MOVED
In order to get a undisrupted journey, you just have to add a &data_freshness=realtime parameter

Section

Field Type Description
type enum string

Type of the section.

  • public_transport: public transport section
  • street_network: street section
  • waiting: waiting section between transport
  • stay_in: this “stay in the vehicle” section occurs when the traveller has to stay in the vehicle when the bus change its routing. Here is an exemple for a journey from A to B: (lollipop line)

    image

  • transfer: transfert section
  • crow_fly: teleportation section. Used when starting or arriving to a city or a stoparea (“potato shaped” objects) Useful to make navitia idempotent. Be careful: no “path” nor “geojson” items in this case

    image

  • on_demand_transport: vehicle may not drive along: traveler will have to call agency to confirm journey
  • bss_rent: taking a bike from a bike sharing system (bss)
  • bss_put_back: putting back a bike from a bike sharing system (bss)
  • boarding: boarding on plane
  • landing: landing off the plane
id string Id of the section
mode enum string Mode of the street network: Walking, Bike, Car
duration int Duration of this section
from places Origin place of this section
to places Destination place of this section
links Array of link Links related to this section
display_informations display_informations Useful information to display
additional_informations enum string Other information. It can be:
  • regular: no on demand transport (odt)
  • has_date_time_estimated: section with at least one estimated date time
  • odt_with_stop_time: odt with fixed schedule, but travelers have to call agency!
  • odt_with_stop_point: odt where pickup or drop off are specific points
  • odt_with_zone: odt which is like a cab, from wherever you want to wherever you want, whenever it is possible
geojson GeoJson
path Array of path The path of this section
transfer_type enum string The type of this transfer it can be: walking, guaranteed, extension
stop_date_times Array of stop_date_time List of the stop times of this section
departure_date_time iso-date-time Date and time of departure
arrival_date_time iso-date-time Date and time of arrival

Path

A path object in composed of an array of path_item (segment).

Path item

Field Type Description
length int Length (in meter) of the segment
name string name of the way corresponding to the segment
duration int duration (in seconds) of the segment
direction int Angle (in degree) between the previous segment and this segment.
  • 0 means going straight
  • > 0 means turning right
  • < 0 means turning left

Hope it’s easier to understand with a picture: image

Fare

Field Type Description
total cost total cost of the journey
found boolean False if no fare has been found for the journey, True otherwise
links link Links related to this object. Link with related tickets

Cost

Field Type Description
value float cost
currency string currency

Ticket

Field Type Description
id string Id of the ticket
name string Name of the ticket
found boolean False if unknown ticket, True otherwise
cost cost Cost of the ticket
links array of link Link to the section using this ticket

Isochrones (currently in Beta)

Try a simple example on Navitia playground (click on “MAP” buttons for “wow effect”)

Try a multi-color example on Navitia playground (click on “MAP” buttons for “WOW effect”)

# Request
curl 'https://api.navitia.io/v1/coverage/sandbox/isochrones?from=stop_area:RAT:SA:GDLYO&max_duration=3600' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

# Response
HTTP/1.1 200 OK

{
    "isochrones":[
        {
            "geojson":{
                "type":"MultiPolygon",
                "coordinates":[
                    [
                        [
                            [
                                2.3186837324,
                                48.9324437042
                            ],
                            [
                                2.3187241561,
                                48.9324771012
                            ],
                            [
                                2.3190737256,
                                48.9327557777
                            ],
                            ["..."],
                            ["..."],
                            ["..."]
                        ]
                    ]
                ]
            }
        }
    ]
}

Also known as /isochrones service.

This service gives you a multi-polygon response which represent a same time travel zone: https://en.wikipedia.org/wiki/Isochrone_map

As you can find isochrone tables using /journeys, this service is only another representation of the same data, map oriented.

It is also really usefull to make filters on geocoded objects in order to find which ones are reachable within a specific time. You just have to verify that the coordinates of the geocoded object are inside the multi-polygon.

Accesses

url Result
/isochrones List of multi-polygons representing one isochrone step. Access from wherever land
/coverage/{region_id}/isochrones List of multi-polygons representing one isochrone step. Access from on a specific coverage

Main parameters

Required Name Type Description Default value
nop from id The id of the departure of your journey. Required to compute isochrones “departure after”
nop to id The id of the arrival of your journey. Required to compute isochrones “arrival before”
yep datetime iso-date-time Date and time to go
yep boundary_duration[] int A duration delineating a reachable area (in seconds). Using multiple boundary makes map more readable
nop forbidden_uris[] id If you want to avoid lines, modes, networks, etc.
Note: the forbidden_uris[] concern only the public transport objects. You can’t for example forbid the use of the bike with them, you have to set the fallback modes for this (first_section_mode[] and last_section_mode[])
nop first_section_mode[] array of string Force the first section mode if the first section is not a public transport one. It takes one the following values: walking, car, bike, bss.
bss stands for bike sharing system.
It’s an array, you can give multiple modes.

Note: choosing bss implicitly allows the walking mode since you might have to walk to the bss station.
Note 2: The parameter is inclusive, not exclusive, so if you want to forbid a mode, you need to add all the other modes.
Eg: If you never want to use a car, you need: first_section_mode[]=walking&first_section_mode[]=bss&first_section_mode[]=bike&last_section_mode[]=walking&last_section_mode[]=bss&last_section_mode[]=bike
walking
nop last_section_mode[] array of string Same as first_section_mode but for the last section walking

Other parameters

Required Name Type Description Default value
nop min_duration int Minimum duration delineating the reachable area (in seconds)
nop max_duration int Maximum duration delineating the reachable area (in seconds)

Route Schedules

#request
$ curl 'https://api.navitia.io/v1/coverage/sandbox/lines/line:RAT:M1/route_schedules' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

#response
HTTP/1.1 200 OK

{
    "pagination": {},
    "links": [],
    "disruptions": [],
    "notes": [],
    "feed_publishers": [],
    "exceptions": [],
    "route_schedules": [
    {
        "display_informations": {
            "direction": "Château de Vincennes (Saint-Mandé)",
            "code": "1",
            "network": "RATP",
            "links": [],
            "color": "F2C931",
            "commercial_mode": "Metro",
            "text_color": "000000",
            "label": "1"
        },
        "table": {
            "headers": [{
                    "display_informations": {
                        "direction": "Château de Vincennes (Saint-Mandé)",
                        "code": "",
                        "description": "",
                        "links": [],
                        "color": "",
                        "physical_mode": "Métro",
                        "headsign": "Château de Vincennes",
                        "commercial_mode": "",
                        "equipments": [],
                        "text_color": "",
                        "network": ""
                    },
                    "additional_informations": ["regular"],
                    "links": [{
                        "type": "vehicle_journey",
                        "id": "vehicle_journey:RAT:RATRM1REGA9828-1_dst_2"
                    }, {
                        "type": "physical_mode",
                        "id": "physical_mode:Metro"
                    }]
                },
                { ... },
                { ... }
            ],
            "rows": [{
                "stop_point": {
                    "codes": [ ... ],
                    "name": "La Défense Grande Arche",
                    "links": [],
                    "physical_modes": [{
                        "name": "Métro",
                        "id": "physical_mode:Metro"
                    }],
                    "coord": {"lat": "48.891935","lon": "2.237883"},
                    "label": "La Défense Grande Arche (Puteaux)",
                    "equipments": [],
                    "commercial_modes": [...],
                    "administrative_regions": [ ... ],
                    "id": "stop_point:RAT:SP:DENFE2",
                    "stop_area": { ... }
                },
                "date_times": [{
                    "date_time": "20160616T093300",
                    "additional_informations": [],
                    "links": [{
                        "type": "vehicle_journey",
                        "value": "vehicle_journey:RAT:RATRM1REGA9828-1_dst_2",
                        "rel": "vehicle_journeys",
                        "id": "vehicle_journey:RAT:RATRM1REGA9828-1_dst_2"
                    }],
                    "data_freshness": "base_schedule"
                }, {
                    "date_time": "20160617T094400",
                    "additional_informations": [],
                    "links": [{
                        "type": "vehicle_journey",
                        "value": "vehicle_journey:RAT:RATRM1REGA9827-1_dst_2",
                        "rel": "vehicle_journeys",
                        "id": "vehicle_journey:RAT:RATRM1REGA9827-1_dst_2"
                    }],
                    "data_freshness": "base_schedule"
                }]
            }]
        },
        "additional_informations": null,
        "links": [],
        "geojson": {}
    }]
}

Also known as /route_schedules service.

This endpoint gives you access to schedules of routes (so a kind of time table), with a response made of an array of route_schedule, and another one of note. You can access it via that kind of url: https://api.navitia.io/v1/{a_path_to_a_resource}/route_schedules

Accesses

url Result
/coverage/{region_id}/{resource_path}/route_schedules List of the entire route schedules for a given resource
/coverage/{lon;lat}/coords/{lon;lat}/route_schedules List of the entire route schedules for coordinates

Parameters

Required Name Type Description Default Value
nop from_datetime iso-date-time The date_time from which you want the schedules
nop duration int Maximum duration in seconds between from_datetime and the retrieved datetimes. 86400
nop items_per_schedule int Maximum number of columns per schedule.
nop forbidden_uris[] id If you want to avoid lines, modes, networks, etc.
nop data_freshness enum Define the freshness of data to use
  • realtime
  • base_schedule
base_schedule
nop disable_geojson boolean remove geojson fields from the response False

Objects

route_schedule object

Field Type Description
display_informations display_informations Usefull information about the route to display
Table table The schedule table

table

Field Type Description
Headers Array of header Informations about vehicle journeys
Rows Array of row A row of the schedule
Field Type Description
additional_informations Array of String Other information: TODO enum
display_informations display_informations Usefull information about the the vehicle journey to display
links Array of link Links to line, vehicle_journey, route, commercial_mode, physical_mode, network

row

Field Type Description
date_times Array of pt-date-time Array of public transport formated date time
stop_point stop_point The stop point of the row

Stop Schedules

Try it on Navitia playground (click on “EXT” buttons to see times)

#request
$ curl 'https://api.navitia.io/v1/coverage/sandbox/lines/line:RAT:M1/stop_schedules' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

#response
HTTP/1.1 200 OK
{
    "stop_schedules": [
        {
            "stop_point": {...},
            "links": [...],
            "date_times": [
                {
                    "date_time": "20160615T115300",
                    "additional_informations": [],
                    "links": [
                        {
                            "type": "vehicle_journey",
                            "value": "vehicle_journey:RAT:RATRM1REGA9869-1_dst_2",
                            "rel": "vehicle_journeys",
                            "id": "vehicle_journey:RAT:RATRM1REGA9869-1_dst_2"
                        }
                    ],
                    "data_freshness": "base_schedule"
                },
                {
                    "date_time": "20160616T115000",
                    "additional_informations": [],
                    "links": [
                        {
                            "type": "vehicle_journey",
                            "value": "vehicle_journey:RAT:RATRM1REGA9868-1_dst_2",
                            "rel": "vehicle_journeys",
                            "id": "vehicle_journey:RAT:RATRM1REGA9868-1_dst_2"
                        }
                    ],
                    "data_freshness": "base_schedule"
                },
                "..."
            ],
            "route": {...},
            "additional_informations": null,
            "display_informations": {
                "direction": "Château de Vincennes (Saint-Mandé)",
                "code": "1",
                "network": "RATP",
                "links": [],
                "color": "F2C931",
                "commercial_mode": "Metro",
                "text_color": "000000",
                "label": "1"
            }
        }
    ],
    "pagination": {...},
    "links": [...],
    "disruptions": [],
    "notes": [],
    "feed_publishers": [...],
    "exceptions": []
}

Also known as /stop_schedules service.

This endpoint gives you access to time tables going through a stop point as: stop_schedules

The response is made of an array of stop_schedule, and another one of note. You can access it via that kind of url: https://api.navitia.io/v1/{a_path_to_a_resource}/stop_schedules

Accesses

url Result
/coverage/{region_id}/{resource_path}/stop_schedules List of the stop schedules grouped by stop_point/route for a given resource
/coverage/{lon;lat}/coords/{lon;lat}/stop_schedules List of the stop schedules grouped by stop_point/route for coordinates

Parameters

Required Name Type Description Default Value
nop from_datetime iso-date-time The date_time from which you want the schedules
nop duration int Maximum duration in seconds between from_datetime and the retrieved datetimes. 86400
nop forbidden_uris[] id If you want to avoid lines, modes, networks, etc.
nop items_per_schedule int Maximum number of datetimes per schedule.
nop data_freshness enum Define the freshness of data to use to compute journeys
  • realtime
  • base_schedule
base_schedule
nop disable_geojson boolean remove geojson fields from the response False

Stop_schedule object

Field Type Description
display_informations display_informations Usefull information about the route to display
route route The route of the schedule
date_times Array of pt-date-time When does a bus stops at the stop point
stop_point stop_point The stop point of the schedule
additional_informations additional_informations Other informations, when no departures

enum values:

  • date_out_of_bounds
  • terminus
  • partial_terminus
  • active_disruption
  • no_departures_known

Departures

Try it on Navitia playground


#Request
$ curl 'https://api.navitia.io/v1/coverage/sandbox/lines/line:RAT:M1/departures?from_datetime=20160615T1337' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

#Response
HTTP/1.1 200 OK
{
   "departures":[
        {
            "display_informations":{
                "direction":"Ch\u00e2teau de Vincennes (Saint-Mand\u00e9)",
                "color":"F2C931",
                "physical_mode":"M?tro",
                "headsign":"Ch\u00e2teau de Vincennes",
                "commercial_mode":"Metro",
                "network":"RATP",
                "..."
            },
            "stop_point":{
                "name":"Esplanade de la D\u00e9fense",
                "physical_modes":[
                   {
                      "name":"M?tro",
                      "id":"physical_mode:Metro"
                   }
                ],
                "coord":{
                   "lat":"48.887843",
                   "lon":"2.250442"
                },
                "label":"Esplanade de la D\u00e9fense (Puteaux)",
                "id":"stop_point:RAT:SP:ESDEN2",
                "..."
            },
            "route":{
                "id":"route:RAT:M1_R",
                "name":"Ch\u00e2teau de Vincennes - La D\u00e9fense",
                "..."
            },
            "stop_date_time":{
                "arrival_date_time":"20160615T133700",
                "departure_date_time":"20160615T133700",
                "base_arrival_date_time":"20160615T133700",
                "base_departure_date_time":"20160615T133700"
            }
        },
        {"...":"..."},
        {"...":"..."},
        {"...":"..."}
   ]
}

Also known as /departures service.

This endpoint retrieves a list of departures from a specific datetime of a selected object. Departures are ordered chronologically in ascending order as: departures

Accesses

url Result
/coverage/{region_id}/{resource_path}/departures List of the next departures, multi-route oriented, only time sorted (no grouped by stop_point/route here)
/coverage/{lon;lat}/coords/{lon;lat}/departures List of the next departures, multi-route oriented, only time sorted (no grouped by stop_point/route here)

Parameters

Required Name Type Description Default Value
nop from_datetime iso-date-time The date_time from which you want the schedules the current datetime
nop duration int Maximum duration in seconds between from_datetime and the retrieved datetimes. 86400
nop count int Maximum number of results. 10
nop forbidden_uris[] id If you want to avoid lines, modes, networks, etc.
nop data_freshness enum Define the freshness of data to use to compute journeys
  • realtime
  • base_schedule
realtime
nop disable_geojson boolean remove geojson fields from the response false

Departure objects

Field Type Description
route route The route of the schedule
stop_date_time Array of stop_date_time Occurs when a bus does a stopover at the stop point
stop_point stop_point The stop point of the schedule

Arrivals

Try it on Navitia playground

curl 'https://api.navitia.io/v1/coverage/sandbox/stop_areas/stop_area:RAT:SA:GDLYO/arrivals' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

HTTP/1.1 200 OK

{
    "arrivals":[
        {
            "display_informations":{
                "direction":"Saint-Lazare (Paris)",
                "code":"14",
                "color":"67328E",
                "physical_mode":"Métro",
                "headsign":"Olympiades",
                "commercial_mode":"Metro",
                "network":"RATP"
            },
            "stop_date_time":{
                "arrival_date_time":"20160615T115400",
                "departure_date_time":"20160615T115400",
                "base_arrival_date_time":"20160615T115400",
                "base_departure_date_time":"20160615T115400",
                "data_freshness":"base_schedule"
            },
            "stop_point":{
                "id":"stop_point:RAT:SP:GDLYO4",
                "name":"Gare de Lyon",
                "label":"Gare de Lyon (Paris)"
            },
            "route":{
                "id":"route:RAT:M14_R",
                "name":"Olympiades - Gare Saint-Lazare"
            }
        },
        {"...": "..."},
        {"...": "..."}
    ]
}

Also known as /arrivals service.

This endpoint retrieves a list of arrivals from a specific datetime of a selected object. Arrivals are ordered chronologically in ascending order.

Accesses

url Result
/coverage/{region_id}/{resource_path}/arrivals List of the arrivals, multi-route oriented, only time sorted (no grouped by stop_point/route here)
/coverage/{lon;lat}/coords/{lon;lat}/arrivals List of the arrivals, multi-route oriented, only time sorted (no grouped by stop_point/route here)

Parameters

they are exactly the same as departures

Traffic reports

#request
$ curl 'http://api.navitia.io/v1/coverage/sandbox/traffic_reports' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

#response, composed by 2 main lists: "traffic_reports" and "disruptions"
HTTP/1.1 200 OK

{
"traffic_reports": [
        "network": {
        #main object (network) and links within its own disruptions
        },
        "lines": [
        #list of all disrupted lines from the network and disruptions links
        ],
        "stop_areas": [
        #list of all disrupted stop_areas from the network and disruptions links
        ],
    ],[
        #another network with its lines and stop areas
    ],
"disruptions": [
        #list of linked disruptions
    ]
}

Also known as /traffic_reports service.

This service provides the state of public transport traffic. It can be called for an overall coverage or for a specific object.

Traffic reports

Parameters

You can access it via that kind of url: https://api.navitia.io/v1/{a_path_to_a_resource}/traffic_reports

For example:

The response is made of an array of traffic_reports, and another one of disruptions.

There are inner links between this 2 arrays: see the inner-reference section to use them.

Traffic report object

#links between objects in a traffic_reports response
{
"traffic_reports": [
    "network": {"name": "bob", "links": [], "id": "network:bob"},
    "lines": [
        {
        "code": "1",
         ... ,
        "links": [ {
            "internal": true,
            "type": "disruption",
            "id": "link-to-green",
            "rel": "disruptions",
            "templated": false
            } ]
        },
        {
        "code": "12",
         ... ,
        "links": [ {
            "internal": true,
            "type": "disruption",
            "id": "link-to-pink",
            "rel": "disruptions",
            "templated": false
            }]
        },
    ],
    "stop_areas": [
        {
        "name": "bobito",
         ... ,
        "links": [ {
            "internal": true,
            "type": "disruption",
            "id": "link-to-red",
            "rel": "disruptions",
            "templated": false
            }]
        },
    ],
 ],
 [
    "network": {
        "name": "bobette",
        "id": "network:bobette",
        "links": [ {
            "internal": true,
            "type": "disruption",
            "id": "link-to-blue",
            "rel": "disruptions",
            "templated": false
            }]
        },
    "lines": [
        {
        "code": "A",
         ... ,
        "links": [ {
            "internal": true,
            "type": "disruption",
            "id": "link-to-green",
            "rel": "disruptions",
            "templated": false
            } ]
        },
        {
        "code": "C",
         ... ,
        "links": [ {
            "internal": true,
            "type": "disruption",
            "id": "link-to-yellow",
            "rel": "disruptions",
            "templated": false
            }]
        },
    "stop_areas": [
        {
        "name": "bobito",
         ... ,
        "links": [ {
            "internal": true,
            "type": "disruption",
            "id": "link-to-red",
            "rel": "disruptions",
            "templated": false
            }]
        },
    ],

],
"disruptions": [
    {
        "status": "active",
        "severity": {"color": "", "priority": 4, "name": "Information", "effect": "UNKNOWN_EFFECT"},
        "messages": [ { "text": "green, super green", ...} ],
        "id": "link-to-green"},
        ...
    },{
        "status": "futur",
        "messages": [ { "text": "pink, floyd pink", ... } ],
        "id": "link-to-pink"},
        ...
    },{
        "status": "futur",
        "messages": [ { "text": "red, mine", ... } ],
        "id": "link-to-red"},
        ...
    },{
        "status": "futur",
        "messages": [ { "text": "blue, grass", ... } ],
        "id": "link-to-blue"},
        ...
    },{
        "status": "futur",
        "messages": [ { "text": "yellow, submarine", ... }
        "id": "link-to-yellow"},
        ...}
    ],
"link": { ... },
"pagination": { ... }
}

Traffic_reports is an array of some traffic_report object.

One traffic_report object is a complex object, made of a network, an array of lines and an array of stop_areas.

A typical traffic_report object will contain:

It means that if a stop_area is used by many networks, it will appear many times.

This typical response means:

Details for disruption objects : disruptions

Objects

Standard Objects

Coord

Lots of object are geographically localized :

Field Type Description
lon float Longitude
lat float Latitude

Iso-date-time

Navitia manages every date or time as a UTC date-time. The web-service

For example: https://api.navitia.io/v1/journeys?from=bob&to=bobette&datetime=20140425T1337

There are lots of ISO 8601 libraries in every kind of language that you should use before breaking down https://youtu.be/-5wpm-gesOY

Public transport objects

Network

{
    "id":"network:RAT:1",
    "name":"RATP"
}

Networks are fed by agencies in GTFS format.

Field Type Description
id string Identifier of the network
name string Name of the network

Line

{
    "id":"line:RAT:M6",
    "name":"Nation - Charles de Gaule Etoile",
    "code":"6",
    "color":"79BB92",
    "opening_time":"053000",
    "closing_time":"013600",
    "routes":[
        {"...": "..."}
    ],
    "commercial_mode":{
        "id":"commercial_mode:Metro",
        "name":"Metro"
    },
    "physical_modes":[
        {
            "name":"Métro",
            "id":"physical_mode:Metro"
        }
    ]
}
Field Type Description
id string Identifier of the line
name string Name of the line
code string Code name of the line
color string Color of the line
opening_time string Opening hour at format HHMMSS
closing_time string Closing hour at format HHMMSS
routes array of route Routes of the line
commercial_mode commercial_mode Commercial mode of the line
physical_mode array of physical_mode Physical modes of the line

Route

{
    "id":"route:RAT:M6",
    "name":"Nation - Charles de Gaule Etoile",
    "is_frequence":"False",
    "line":{
        "id":"line:RAT:M6",
        "name":"Nation - Charles de Gaule Etoile",
        "...": "..."
    },
    "direction":{
        "id":"stop_area:RAT:SA:GAUET",
        "name":"Charles de Gaulle - Etoile (Paris)",
        "...": "..."
    }
}
Field Type Description
id string Identifier of the route
name string Name of the route
is_frequence bool Is the route has frequency or not
line line The line of this route
direction place The direction of this route

As “direction” is a place , it can be a poi in some data.

Stop Point

{
    "id":"stop_point:RAT:SP:GARIB2",
    "name":"Garibaldi",
    "label":"Garibaldi (Saint-Ouen)",
    "coord":{
        "lat":"48.906032",
        "lon":"2.331733"
    },
    "administrative_regions":[{"...": "..."}],
    "equipments":[{"...": "..."}],
    "stop_area":{"...": "..."}
}
Field Type Description
id string Identifier of the stop point
name string Name of the stop point
coord coord Coordinates of the stop point
administrative_regions array of admin Administrative regions of the stop point in which is the stop point
equipments array of string list of equipment of the stop point
stop_area stop_area Stop Area containing this stop point

Stop Area

{
    "id":"stop_area:RAT:SA:GAUET",
    "name":"Charles de Gaulle - Etoile",
    "label":"Charles de Gaulle - Etoile (Paris)",
    "coord":{
        "lat":"48.874408",
        "lon":"2.295763"
    },
    "administrative_regions":[
        {"...": "..."}
    ]
}
Field Type Description
id string Identifier of the stop area
name string Name of the stop area
label string Label of the stop area. The name is directly taken from the data whereas the label is something we compute for better traveler information. If you don’t know what to display, display the label.
coord coord Coordinates of the stop area
administrative_regions array of admin Administrative regions of the stop area in which is the stop area
stop_points array of stop_point Stop points contained in this stop area

Commercial Mode

{
    "id":"commercial_mode:Metro",
    "name":"Metro"
}
Field Type Description
id string Identifier of the commercial mode
name string Name of the commercial mode
physical_modes array of physical_mode Physical modes of this commercial mode

Physical Mode

{
    "id":"physical_mode:Tramway",
    "name":"Tramway"
}
Field Type Description
id string Identifier of the physical mode
name string Name of the physical mode
commercial_modes array of commercial_mode Commercial modes of this physical mode

Physical modes are fastened and normalized. If you want to propose modes filter in your application, you should use physical_mode rather than commercial_mode.

Here is the valid id list:

You can use these ids in the forbidden_uris[] parameter from journeys parameters for exemple.

Company

{
    "id": "company:RAT:1",
    "name": "RATP"
}
Field Type Description
id string Identifier of the company
name string Name of the company

Place

A container containing either a admin, poi, address, stop_area, stop_point

{
    "id": "admin:2191338",
    "name": "Quartier des Épinettes (75017)",
    "quality": 70,
    "embedded_type": "administrative_region",
    "administrative_region": {
        "...": "..."
    }
}
Field Type Description
id string The id of the embedded object
name string The name of the embedded object
quality optional integer The quality of the place
embedded_type embedded_type The type of the embedded object
administrative_region optional admin Embedded administrative region
stop_area optional stop_area Embedded Stop area
poi optional poi Embedded poi
address optional address Embedded address
stop_point optional stop_point Embedded Stop point

Trip

A trip corresponds to a scheduled vehicle circulation (and all its linked real-time and disrupted routes).

An example : a train, routing a Paris to Lyon itinerary every day at 06h29, is the “Trip” named “6641”.

{
    "id": "OIF:67308746-10-1",
    "name": "67308746"
}
Field Type Description
id string The id of the trip
name string The name of the trip

It also encapsulates many instances of vehicle_journey, accessible with the url:

https://api.navitia.io/v1/coverage/sandbox/trips/{trip.id}/vehicle_journeys.

Pt_object

A container containing either a network, commercial_mode, line, route, stop_area, stop_area, trip

{
    "id": "OCE:SN009862F01013",
    "name": "OCE:SN009862F01013",
    "quality": 0,
    "embedded_type": "trip",
    "trip": {
        "id": "OCE:SN009862F01013",
        "name": "9862"
    }
}
Field Type Description
id string The id of the embedded object
name string The name of the embedded object
quality optional integer The quality of the object
embedded_type embedded_type The type of the embedded object
stop_area optional stop_area Embedded Stop area
stop_point optional stop_point Embedded Stop point
network optional network Embedded network
commercial_mode optional commercial_mode Embedded commercial_mode
stop_area optional stop_area Embedded Stop area
line optional line Embedded line
route optional route Embedded route
trip optional trip Embedded trip

Real time and disruption objects

Disruption

{
    "id": "ce7e265d-5762-45b6-ab4d-a1df643dd48d",
    "status": "active",
    "disruption_id": "ce7e265d-5762-45b6-ab4d-a1df643dd48d",
    "impact_id": "ce7e265d-5762-45b6-ab4d-a1df643dd48d",
    "severity": {
        "name": "trip delayed",
        "effect": "SIGNIFICANT_DELAYS"
    },
    "application_periods": [
        {
            "begin": "20160608T215400",
            "end": "20160608T230959"
        }
    ],
    "messages": [
        {"text": "Strike"}
    ],
    "updated_at": "20160617T132624",
    "impacted_objects": [
        {"...": "..."}
    ],
    "cause": "Cause...",
    "category": "incident"
}
Field Type Description
id string Id of the disruption
status between: “past”, “active” or “future” state of the disruption. The state is computed using the application_periods of the disruption and the current time of the query.
disruption_id string for traceability: Id of original input disruption
impact_id string for traceability: Id of original input impact
severity severity gives some categorization element
application_periods array of period dates where the current disruption is active
messages message text to provide to the traveler
updated_at iso-date-time date_time of last modifications
impacted_objects array of impacted_object The list of public transport objects which are affected by the disruption
cause string why is there such a disruption?
category string (optional) The category of the disruption, such as “construction works” or “incident”

Impacted_object

{
    "pt_object": {
        "id": "id_of_the_line",
        "name": "name of a lne",
        "embedded_type": "line",
        "line": {
            "...": "..."
        }
    },
    "impacted_section": {
        "...": "..."
    }
}
Field Type Description
pt_object pt_object The impacted public transport object
impacted_section optional impacted_section Only for line section impact, the impacted section
impacted_stops optional array of impacted_stop Only for trip delay, the list of delays, stop by stop

Impacted_section

{
    "from": {
        "embedded_type": "stop_area",
        "id": "C",
        "name": "C",
        "stop_area": {
            "...": "..."
        }
    },
    "to": {
        "embedded_type": "stop_area",
        "id": "E",
        "name": "E",
        "stop_area": {
            "...": "..."
        }
    }
}
Field Type Description
from pt_object The beginning of the section
to pt_object The end of the section

Impacted_stop

{
    "stop_point": {
        "...": "..."
    },
    "amended_arrival_time": "073600",
    "amended_departure_time": "073600",
    "base_arrival_time": "073600",
    "base_departure_time": "073600",
    "cause": "",
    "stop_time_effect": "delayed"
}
Field Type Description
stop_point stop_point The impacted stop point of the trip
amended_departure_time string New departure hour (format HHMMSS) of the trip on this stop point
amended_arrival_time string New arrival hour (format HHMMSS) of the trip on this stop point
base_departure_time string Base departure hour (format HHMMSS) of the trip on this stop point
base_arrival_time string Base arrival hour (format HHMMSS) of the trip on this stop point
cause string Cause of the modification
stop_time_effect Enum Can be: “added”, “deleted”, or “delayed”.

Message

{
    "text": "Strike",
    "channel": {
        "...": "..."
    }
}
Field Type Description
text string a message to bring to a traveler
channel channel destination media. Be careful, no normalized enum for now

Severity

Severity object can be used to make visual grouping.

{
    "color": "#FF0000",
    "priority": 42,
    "name": "trip delayed",
    "effect": "SIGNIFICANT_DELAYS"
}
Field Type Description
color string HTML color for classification
priority integer given by the agency : 0 is strongest priority. it can be null
name string name of severity
effect Enum Normalized value of the effect on the public transport object See the GTFS RT documentation at https://developers.google.com/transit/gtfs-realtime/reference#Effect

Channel

{
    "id": "rt",
    "content_type": "text/html",
    "name": "rt",
    "types": [
        "web",
        "mobile"
    ]
}
Field Type Description
id string Identifier of the address
content_type string Like text/html, you know? Otherwise, take a look at http://www.w3.org/Protocols/rfc1341/4_Content-Type.html
name string name of the Channel

Period

{
    "begin": "20160608T215400",
    "end": "20160608T230959"
}
Field Type Description
begin iso-date-time Beginning date and time of an activity period
end iso-date-time Closing date and time of an activity period

Street network objects

Poi Type

#request
$ curl 'https://api.navitia.io/v1/coverage/sandbox/poi_types' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

/poi_types lists groups of point of interest. You will find classifications as theater, offices or bicycle rental station for example.

Field Type Description
id string Identifier of the poi type
name string Name of the poi type

Poi

#useless request, with huge response
$ curl 'https://api.navitia.io/v1/coverage/sandbox/pois' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

#inverted geocoding request, more usable
$ curl 'https://api.navitia.io/v1/coverage/sandbox/coords/2.377310;48.847002/pois' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

#very smart request
#combining filters to get some specific POIs, as bicycle rental stations, 
#nearby a coordinate
$ curl 'https://api.navitia.io/v1/coverage/sandbox/poi_types/poi_type:amenity:bicycle_rental/coords/2.377310;48.847002/pois' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

Poi = Point Of Interest

Field Type Description
id string Identifier of the poi
name string Name of the poi
label string Label of the poi. The name is directly taken from the data whereas the label is something we compute for better traveler information. If you don’t know what to display, display the label.
poi_type poi_type Type of the poi

Address

Field Type Description
id string Identifier of the address
name string Name of the address
label string Label of the adress. The name is directly taken from the data whereas the label is something we compute for better traveler information. If you don’t know what to display, display the label.
coord coord Coordinates of the address
house_number int House number of the address
administrative_regions array of admin Administrative regions of the address in which is the stop area

Administrative region

Field Type Description
id string Identifier of the address
name string Name of the address
label string Label of the administrative region. The name is directly taken from the data whereas the label is something we compute for better traveler information. If you don’t know what to display, display the label.
coord coord Coordinates of the address
level int Level of the admin
zip_code string Zip code of the admin

Cities are mainly on the 8 level, dependant on the country (http://wiki.openstreetmap.org/wiki/Tag:boundary%3Dadministrative)

Other objects

pt-date-time

pt-date-time (pt stands for “public transport”) is a complex date time object to manage the difference between stop and leaving times at a stop.

Field Type Description
additional_informations Array of String Other information: TODO enum
departure_date_time iso-date-time A date time
arrival_date_time iso-date-time A date time
links Array of link internal links to notes

note

Field Type Description
id String id of the note
value String The content of the note

stop_date_time

Field Type Description
date_time pt-date-time A public transport date time
stop_point stop_point A stop point

Embedded type

Enum used to identify what kind of objects /places, /pt_objects or /disruptions services are managing.

Value Description
administrative_region a city, a district, a neighborhood
network a public transport network
commercial_mode a public transport branded mode
line a public transport line
route a public transport route
stop_area a nameable zone, where there are some stop points
stop_point a location where vehicles can pickup or drop off passengers
address a point located in a street
poi a point of interest
trip a trip

equipment

Enum from

display informations

Field Type Description
network String The name of the network
direction String A direction
commercial_mode String The commercial mode
physical_mode String The physical mode
label String The label of the object
color String The hexadecimal code of the line
code String The code of the line
description String A description
equipments Array of String list of equipment of the object

See interface section.

Special Parameters

datetime

A date time with the format YYYYMMDDThhmmss

depth

This tiny parameter can expand Navitia power by making it more wordy. As it is valuable on every API, take a look at depth

Misc mechanisms (and few boring stuff)

Multiple journeys

Navitia can compute several kind of journeys with a journey query.

The RAPTOR algorithm used in Navitia is a multi-objective algorithm. Thus it might return multiple journeys if it cannot know that one is better than the other. For example it cannot decide that a one hour journey with no connection is better than a 45 minutes journey with one connection (it is called the pareto front).

If the user asks for more journeys than the number of journeys given by RAPTOR (with the parameter min_nb_journeys or count), Navitia will ask RAPTOR again, but for the following journeys (or the previous ones if the user asked with datetime_represents=arrival).

Those journeys have the next (or previous) value in their tags.

Journey qualification process

Since Navitia can return several journeys, it tags them to help the user choose the best one that matches their needs. Here are some tagging rules: - there is only one “best” itinerary - itineraries with other types are displayed only if they are relevant - and for a specific type, you may find many relevant itinerary

For example, for a specific request, you can find the “best” itinerary, 2 “less_fallback_walk” ones (with less walking, but taking more time) and no “comfort” (the “best” one is the same as the “comfort” one for example).

The different journey types are:

Type Description
best The best journey if you have to display only one.
rapid A good trade off between duration, changes and constraint respect
comfort A journey with less changes and walking
car A journey with car to get to the public transport
less_fallback_walk A journey with less walking
less_fallback_bike A journey with less biking
less_fallback_bss A journey with less bss
fastest A journey with minimum duration
non_pt_walk A journey without public transport, only walking
non_pt_bike A journey without public transport, only biking
non_pt_bss A journey without public transport, only bike sharing

On demand transportation

Some transit agencies force travelers to call them to arrange a pickup at a particular place or stop point.

Besides, some stop times can be “estimated” in data by design :

After all, the stop points can be standard (such as bus stop or railway station) or “zonal” (where agency can pick you up you anywhere, like a cab).

That’s some kind of “responsive locomotion” (ɔ).

So public transport lines can mix different methods to pickup travelers:

Lexicon

Introduction

The world of public transportation is really specific, you will see here a small introduction to it. A lot of people in the world of public transportation use different words to speak about the same thing. Here are the definitions of terms employed in www.navitia.io

You can read a mobility lexicon at https://github.com/OpenTransport/vocabulary/blob/master/vocabulary.md

You will often read “PT” in this document. PT stands for public transport.

Stop Point

A stop point is the physical object were someone waits for his bus (subway, or whatever type of vehicle you can have in a public transport system).

Stop Area

A stop area is a collection of stop points. Generally there are at least two stop points per stop area, one per direction of a line. Now think of a hub, you will have more than one line. Therefore your stop area will contain more than two stop points. In particular cases your stop area can contain only one stop point.

Some datasets do not contain any stop area.

Connection

This object links two stop points together (named origin and destination). It is the walkable part of a journey.

Journey Pattern

A journey pattern is an ordered list of stop points. Two vehicles that serve exactly the same stop points in exactly the same order belong to to the same journey pattern.

Route

A route is a collection of journey pattern that match the same commercial direction.

Line

A line is a collection of routes. Most of the time you’ll just have just two routes. This object is called route in the GTFS format.

Stop Time

A stop time represents the time when a bus is planned to arrive and to leave a stop point.

Errors

Code 40x

When there’s an error you’ll receive a response with a error object containing a unique error id

#request
$ curl 'https://api.navitia.io/v1/coverage/sandbox/stop_areas/wrong-one' -H 'Authorization: 3b036afe-0110-4202-b9ed-99718476c2e0'

#response
HTTP/1.1 404 OK

{
    "error": {
        "id": "bad_filter",
        "message": "ptref : Filters: Unable to find object"
    }
}

This errors appears when there is an error in the request

The are two possible 40x http codes :

Error id Description
date_out_of_bounds When the given date is out of bounds of the production dates of the region
no_origin Couldn’t find an origin for the journeys
no_destination Couldn’t find an destination for the journeys
no_origin_nor_destination Couldn’t find an origin nor a destination for the journeys
unknown_object As it’s said
Error id Description
bad_filter When you use a custom filter
unable_to_parse When you use a mal-formed custom filter

Code 50x

Ouch. Technical issue :/