Mecatran Urbiplan: web-services specifications

July 2023

Introduction

Welcome to the Urbiplan web-services specifications and developer guide. Urbiplan is a platform giving an easy-to-use RESTful interface to client to access both static and real-time transit data. This guide explains how this RESTful HTTP API works (request, response, JSON or XML format).

Note

Please email your contact point at the agency or for any technical request.

Architecture

The API is accessible through simple RESTful HTTP requests such as:

https://{site}.mecatran.com/utw/ws/gtfs/routes/moontransit?apiKey={apiKey}

The base domain xyz for your configuration should be given to you, alongside this documentation.

API key control

All methods requires an apiKey parameter which is the key that should have been provided to you when you registered to the API. An apiKey is valid for one “feed” only (usually a transit agency). Please check with your agency regarding the terms of service (rate limiting, key transferability…) of this API.

The apiKey can also be specified in the HTTP header of the request, using the parameter Authorization: ApiKey xxx.

Some API keys can be restricted to a given list of origins (for keys used on client browsers with CORS), or restricted to a list of IPs (for keys used by server backends).

Output format selection

The API response is available in JSON format (XML is deprecated and not supported anymore). The Accept: HTTP header value should be application/json. The Accept: header parameter is mandatory for all requests, do not rely on the default returned format as it may change in the future. We strongly recommand to use the JSON version of the API. Note: the use of JSONP format is also discouraged, as the server properly handle CORS mechanism (preferred).

application/json

Return the response in JSON format. The JSON answer can be converted into a Javascript object quite easily in Javascript code.

application/x-javascript

Return the response in JSONP format. If you use this format, you must also add a “callback” parameter which name is the name of the function you want to callback. The answer is a javascript code that simply returns the callback function, whose name is specified using the “callback” parameter, and with the data payload as single argument.

Note

To test/debug the API you can use the curl command-line tool as specified below:

curl --header "Accept: application/json" \
     --header "Authorization: ApiKey xxxx" \
     "http://your-url" > debug.json

The proxy uses the JAX-RS standard for RESTful services, implemented through the EasyREST library. JSON encoding uses the Jackson v2 library. For more information on Jackson please consult this link.

The web-service is accessible at the following address: https://{site}.mecatran.com/utw/ws/{domain}/{method}/{feedKey}/{objectId}?params=...

Each web-service domain/method usually needs a mandatory feedKey path parameter which specifies the data feed bundle you want to query. Some methods require the ID of the object that you want to query. Some methods accept optional query parameters to further refine returned informations.

/ws/server-info

Response

Various server parameters such as version. JSON example:

{
  "apiVersion" : "1.2.27",
  "version" : "1.4.85"
}
version

String. Server version (major.minor.release)

apiVersion

String. API version (major.minor.release) All identical major versions are backward-compatible, they only add new fields to existing data.

/ws/gtfs/feed-info/{feedKey}

Response

A static feed information descriptor. JSON example:

{
  "id" : "moon-transit",
  "timestamp" : 1426847497598
}
id

The feed key, identical as the one specified in the request.

timestamp

A timestamp of the static data version. If this timestamp changes, that means that the static data has been updated, and you should update any values kept in a cache. The timestamp is also returned in the real-time stop departure query, to help you minimize the number of requests to the server.

/ws/gtfs/agencies/{feedKey}

Request parameters

includeRoutes

Boolean value (true/false) specifying if you want to include in the response the route list for each agency. Default to “false”.

Response

A list of transitAgency objects. JSON example:

[{ "id"       : "moon-rail",
   "lang"     : "eo",
   "name"     : "Moon Rail",
   "phone"    : "(+999) 01 42",
   "timezone" : "Moon/Copernicus",
   "url"      : "http://moonrail.com/",
   "routes" : [{
      "agencyId"   : "moon-rail",
      "color"      : "ae6f09",
      "id"         : "01",
      "longName"   : "Clavius - Seleucus",
      "shortName"  : "CS",
      "textColor"  : "FFFFFF",
      "type"       : 3
   }, {
       ...
   }]
}] 
id

String. Internal unique ID of the agency.

lang

ISO 639-1 two-letters code of the main language for this agency.

name

Name of the agency.

phone

Contact phone number of the agency.

timezone

Timezone code of the agency. All date/times should be computed relative to this timezone if no other timezone are specified for a particular stop.

url

Main agency website URL.

routes

List of routes belonging to this timezone. See routes list method for more informations on the meaning of each route entity fields.

/ws/gtfs/routes/{feedKey}

Request parameters

includePatterns

Boolean value (true/false) specifying if you want to include in the response the route trip patterns and merged patterns for each route. A pattern is a distinct ordered list of stops. Merged patterns are a merged view of each pattern for a direction, one per direction. Default to “false”.

routeLookAheadDays

If set, filter the route list with only routes that are active (having at least one trip running) between now and now + routeLookAheadDays days. If not set, the route list is not filtered.

codeQuery, nameQuery

If present, restrict the list of returned routes to the one containing the given substring in the code (ie short name) or long name component.

latitude, longitude, radiusMeters

If those 3 parameters are present, retrict the list of returned routes to the one having stops in the given bounded circle, whose center is at (latitude, longitude) and having radiusMeters.

Response

A list of transitRoute objects. JSON example:

[
    {
        "agencyId": "moon-rail",
        "id": "01",
        "longName": "Clavius - Seleucus",
        "shortName": "CS",
        "color": "AE6F09",
        "textColor": "FFFFFF",
        "type": 3,
        "group": "rail",
        "direction0Name": "Clavius",
        "direction1Name": "Seleucus",
        "fromDate": "2019-07-01T00:00:00Z",
        "toDate": "2020-07-03T00:00:00Z",
        "wheelchairAccessiblePerc": 0,
        "wheelchairUnaccessiblePerc": 0,
        "patterns": [
            {   "directionId": 0,
                "stops": [ { "stopId": "S34" }, ... { "stopId": "S44" } ]
            }
        ]
    },
    ...
]
id

String. Internal unique ID of the route.

agencyId

String. Internal ID of the agency which this route is part of.

shortName

Code for this route. Optional.

longName

Route long name.

color

Background color of the route, in hex triplet RGB “HTML” standard notation. Optional, default to white. Example: 000000 - black; ffffff - white; ff0000 - red; 00ff00 - green; 0000ff - blue.

textColor

Text color of the route. Optional, default to black. Same format as the background color.

type

Type of route (see GTFS specifications for more informations):

0

Tram, Streetcar, Light rail. Any light rail or street level system within a metropolitan area.

1

Subway, Metro. Any underground rail system within a metropolitan area.

2

Rail. Used for intercity or long-distance travel.

3

Bus. Used for short- and long-distance bus routes.

4

Ferry. Used for short- and long-distance boat service.

5

Cable car. Used for street-level cable cars where the cable runs beneath the car.

6

Gondola, Suspended cable car. Typically used for aerial cable cars where the car is suspended from the cable.

7

Funicular. Any rail system designed for steep inclines.

patterns

The list of patterns for the route. Each pattern is a different ordered list of stops for different direction. Please note that patterns that are sub-patterns of others are not merged. For example if some trips have pattern ABC and other trips have pattern ABCD two patterns are given: ABC and ABCD.

patterns/directionId

The directionId of the trips for this pattern. Optional. If trips have no direction ID, their pattern will have no direction ID. You should handle the case where this field is not present.

patterns/tripsCount

Total number of trips of this pattern.

patterns/tripDaysCount

Total number of days for each trip of this pattern (the sum of the number of days each trip is applicable). In order to get the relative importance of a pattern inside a route, you can divide this number by the sum of tripDaysCount for each pattern of the route.

patterns/stopIds

The ordered list of stop IDs for this pattern.

direction0Name, direction1Name

The name of the main route headsign in the two directions. Note: if this value is not present in the source data, it is computed according to the route trip headsigns in each direction. The value is computed by appending, in decreasing order of usage, the most common headsigns (a headsign that is used by more than 10% of the trips), limited to the most common 3.

fromDate, toDate

The first and last date of activity for the route. Note: those values are null (not present) if a route is empty. Date format is ISO 8601. Only the date portion is relevant, time is always midnight UTC whatever the time of the first or last trip (logical date).

wheelchairAccessiblePerc, wheelchairUnaccessiblePerc

The percentage of trips-days with wheelchair-accessible trips (respectively, wheelchair-unaccessible trips). Note: the sum of the two values is not always equals to 100%, as some trips can have an undefined wheelchair-accessibility, in which case it does not count in the sum of any of the two values. To consider a route to be wheelchair accessible, you can either take a minimal value for wheelchairAccessiblePerc (such as 95% or 100%), or take a maximal value for wheelchairUnaccessiblePerc (such as 0% or 5%), depending if you want to consider the undefined trips as accessible or not. Note: The wheelchair accessibility is really defined trip by trip and stop by stop, and those values should be taken into account to be precise (see stops and real-time departures API end-points).

/ws/gtfs/stops/{feedKey}

Request parameters

includeStops

Boolean value (true/false) specifying if you want to include stops in the response. Default to “true”. A stop can (optionally) belong to a parent station.

includeStations

Boolean value (true/false) specifying if you want to include stations in the response. Default to “true”. A station is an aggregate of stops.

includeRoutes

Boolean value (true/false) specifying if you want to include routes details in the response. Default to “false”. The route list of a parent station is the union of the route list of its children (for direction, will return the union of children’s directions).

routeLookAheadDays

If set, filter each stop route list with only routes that are active (having at least one trip running) between now and now + routeLookAheadDays days. If not set, the route list is not filtered.

codeQuery

If provided, only return stops whose code exactly matches (case and accent sensitive) codeQuery string.

nameQuery

If provided, only return stops whose name contains the provided nameQuery string. Do not take accents or lower/upper casing into consideration. For example all the queries “cafe”, “café”, “CAFE” or “CAFÉ” will match stops “Café”, “FOO CAFÉ BAR”, “cafeteria”, etc…

latitude, longitude, radiusMeters

If those 3 parameters are present, retrict the list of returned stops to the one in the given bounded circle, whose center is at (latitude, longitude) and having radiusMeters. Also return a distance field for each stop in the answer which is the distance in meters between the stop and the center of the circle given in parameter.

Response

A list of transitStop objects. JSON example:

[{
    "id" : "ARIS01",
    "parentId" : "ARIS",
    "latitude" : 47.445178,
    "longitude" : 23.712889,
    "name" : "Aristarchus",
    "type" : 0,
    "wheelchairBoarding" : 0,
    "routeIds" : [ "01" ],
 }, {
    "id" : "TYCHO",
    "latitude" : -43.31945,
    "longitude" : 11.36548,
    "name" : "Tycho South",
    "type" : 1,
    "wheelchairBoarding" : 0,
    "routeIds" : [ "01", "02" ],
}, ...
id

String. Internal unique ID of the stop.

extId

String. External / extra ID of the stop, if present. Optional.

parentId

String. Internal ID of the parent station, if this stop belongs to a station. Optional.

latitude, longitude

Floating-point value (double). WGS84 degrees. Coordinates of the point.

name

String. UTF-8 name of the stop or station.

wheelchairBoarding

Integer. This field identifies whether wheelchair boardings are possible from the specified stop or station. The field can have the following values:

0

(Default value) indicates that there is no accessibility information for the stop;

1

indicates that at least some vehicles at this stop can be boarded by a rider in a wheelchair;

2

wheelchair boarding is not possible at all at this stop.

type

The type field can have the following values:

0

Stop. A location where passengers board or disembark from a transit vehicle;

1

Station. A physical structure or area that contains one or more stop.

routeIds

A list of route IDs passing by this stop. Present if the includeRoutes parameter is set.

Caution

Warning: Deprecated field. Please use routes/id instead.

routes/id

ID of the route passing by this stop. Present if the includeRoutes parameter is set.

routes/directionIds

List of direction IDs for the route passing by this stop. Can contains 0, 1 or both, depending on the set of route trips passing by this stop. Present if the includeRoutes parameter is set.

/ws/gtfs/fares/{feedKey}

Response

A list of transitFare objects. JSON example:

[ {
    "id" : "STD",
    "agencyId" : "MOONTRANSIT",
    "currencyCode" : "EUR",
    "price" : 1.50,
    "paymentMethod" : 0,
    "transfers" : 0,
    "transfersDurationSec" : 0,
    "rules" : [ {
        "originZoneId" : "TYCHO"
        "destinationZoneId" : "ALBATEGNIUS"
    }, {
        "routeId" : "CLAVIUS"
    } ]
}, ...
id

String. Unique ID of the fare.

agencyId

String. ID of the agency of the fare. Not frequently used. Optional.

currencyCode

String. ISO 4217 currency code, such as EUR or USD.

price

Float. Price of the fare.

paymentMethod

Integer. Determine if the fare can be paid on board or before boarding.

0

Fare is paid on board.

1

Fare must be paid before boarding.

transfers

Integer. Optional. If present, the maximum number of transfers. 0 means that no transfers is allowed. If not present, an infinite number of transfers is allowed.

transfersDurationSec

Specifies the length of time in seconds before a transfer expires.

rules

Optional. A list of rules for this fare to apply. This closely match the GTFS fares standard. For more information on how fares work, please see this link .

/ws/realtime/stop/{feedKey}/{stopId}

Request parameters

stopId

The ID of the stop you want to request real-time info. This can be the ID of a stop (type 0), or a station (type 1). In case of a station, the aggregation of sub-stops (departures, routes and alerts) will be returned. The stop field of the returned response will correspond to the stop given in the request.

viaStopId

The ID of the stop to restrict list of departures. The returned departure list will only contains trips passing through this stop (or through any sub-stops of a station if the viaStopId refers to a station). If this option is enabled, the served stops list will only include the via stops, unless you activate the includeServedStops option in which case the full list of served stop will be included. Optional, do not restrict anything if not defined.

includeServedStops

Boolean value (true/false) specifying if you want to include the full list of served stops for each departure trip. Optional, default to “false”.

Caution

Warning! In case the API provide real-time data, some configuration are not able to provide real-time arrival times for servedStops, in which case it’s not advised to use this option. In any case, it’s better to contact Mecatran technical support if you plan to use this option.

date

Date/time in ISO-8601 format for which to request real-time information for this stop. Format: yyyy-MM-dd'T'HH:mm:ssZ, as for example: 2015-11-22T12:30:40Z (date/time defined in UTC). Default to the current date/time. Optional.

includeAlerts

Boolean value (true/false) specifying if you want to include alerts in the response. Default to “false”. Optional. Note: alerts will be included only if they are available for this feed.

alertChannel

Alert channel to use for returning data. Check with us for possible values.

lookAheadSec

Number of seconds to look ahead for departures. If this parameter is set, then only departures between the provided date/time and date/time + look ahead will be returned in the answer. If not provided, default to 86400 (24h). Optional.

preferredLang

ISO 639-1 two-letters language code to select alert data preferred language. Please note that in case the preferred language is not available as translation on the server, the alert title and description will be returned with a default language. Default to “en”. Optional.

routeLookAheadDays

Number of days in the future to compute the list of routes passing by. If not specified, the list of routes is all the routes passing by this stop for all dates. If specified, only consider “now” up to this number of days in the future to compute this route list. Useful if you do not want to include routes active only during some time in the year, for example to hide summer routes in winter.

extra

Name(s) of the stop extra (non-standard) field(s) to return. This parameter can be specified multiple times if you would like to get multiple extra stop fields in the answer.

Response

A transitStopRealTimeInfo object. JSON example:

{
    "feedTimestamp": 1570209109385,
    "alerts": [
        {   "activeFrom": "2019-10-07T22:00:00Z",
            "description": "Due to a strike tomorrow, routes CS, TY and XD will not be running.",
            ...      
        }
    ],
    "departures": [
        {   "alertIds": [],
            "departureTime": "2019-10-07T11:00:00Z",
            "directionId": 0,
            "dropoff": 2,
            "exactTime": true,
            "headsign": "Tycho South",
            "pickup": 2,
            "realtime": true,
            "routeId": "CS",
            "theorical": false,
            "tripId": "VN53",
            "tripIndex": 0,
            "tripIndexMax": 14,
            "wheelchairAccessible": 0
        },
        ...
    ],
    "routes": [
        {
            "agencyId": "moon-rail",
            "id": "01",
            "longName": "Clavius - Seleucus",
            "shortName": "CS",
            "color": "AE6F09",
            "textColor": "FFFFFF",
            "type": 3,
            "group": "rail",
            "direction0Name": "Clavius",
            "direction1Name": "Seleucus",
            "fromDate": "2019-07-01T00:00:00Z",
            "toDate": "2020-07-03T00:00:00Z",
        }
    ],
    "stop": {
        "id": "TC-3",
        "latitude": -43.31,
        "longitude": -11.36,
        "name": "Tycho Central",
        "parentId": "TC",
        "type": 0,
        "wheelchairBoarding": 0
    }
}    
alerts

A list of alerts, active for this stop (active for at least a next departure, a route passing by, or a general alert). Please see alerts list web-service for more info on the alert fields. This list is only present if the request option “includeAlerts” is set. Please note that when no departures are present in the answer for the given date, alerts active for this stop are present, if they are active for the selected date.

feedTimestamp

The timestamp of the static data, as returned in the feed-info endpoint. If this timestamp changes, you should probably update any cached values on the client side (for example, a list of stops or routes kept in cache).

departures

A list of departure from this stop for a given route.

departures/alertIds

A list of ID of related alerts for this departure. Can be empty if no alert are active for this departure. The alert with this ID is present in the alerts list of the transitStopRealTimeInfo object. This list is only present if the request option “includeAlerts” is set.

departures/arrivalTime, departures/departureTime

UTC ISO 8601 date/time for the arrival or departure time, either actual, expected or scheduled. Sometimes no dwell time are took into account into the system so arrival and departure time will be the same value.

departures/scheduledArrivalTime, departures/scheduledDepartureTime

UTC ISO 8601 date/time for the scheduled (theoretical) arrival or departure time. This field is only present when the flag “realtime” is set to true. If the realtime flag is not set, use the arrivalTime and departureTime field for scheduled time.

departures/arrivalDeviationSec, departures/departureDeviationSec

Number of seconds of deviation between scheduled (theoretical) and real-time (estimated) arrival or departure time. Those fields are only present when the flag “realtime” is set to true, and if the departure or arrival date time is present.

departures/directionId

This field is used to classify departures in two “logical” groups (for example inbound/outbound, eastward/westward, etc…). 0 or 1. Optional (you have to take care of a missing value, which means “undefined direction”).

departures/headsign

Headsign of the departure.

departures/routeId

ID of the route for this departure. The route data is contained in the routes list.

departures/realtime

Boolean value. True if this departure is given by real-time monitoring data, false if real-time data is not available, in which case the scheduled departure time is given instead.

departures/tripId

Internal unique ID of the trip corresponding for this departure.

departures/stopId

The ID of the stop for this departure. Present only if the request is made for a station; otherwise the ID of a departure stop is always the ID of the requested stop and thus is not needed.

departures/pickup, departures/dropoff

The type of pickup and dropoff for this departure. 0: regular (always stop for pickup or dropoff, default for tram or metro). 1: forbidden (in case of local traffic restriction for example: pickup or dropoff alongside the route at some point can be forbidden). 2: must phone agency to arrange for pickup/dropoff. 3: Ask the driver (default for bus).

departures/servedStops

A list of stops which are served by this trip. This list is in order. The list start at the first stop after the current stop, the portion before the current stop is not included. Be careful: the list will include stops even if a dropoff is forbidden (dropoff type 1).

departures/servedStops/stopId

The ID of the stop served.

departures/servedStops/dropoff

The dropoff type for this stop (see dropoff type constants above).

departures/servedStops/arrivalTime

The arrival time (schedule or real-time, depending on the real-time flag) at the stop.

departures/servedStops/realTime

The real-time flag. True if this arrival time is real-time, false if this is only a scheduled time.

departures/servedStops/scheduledArrivalTime

If real-time flag is enabled (true), contains the original scheduled arrival time. Not present if real-time flag is not enabled (false).

departures/servedStops/alertIds

A list of alert IDs applicable for this stop. This list is only present if the request option “includeAlerts” is set.

departure/wheelchairAccessible

Integer. This field identifies whether this trip is wheelchair-accessible. The field can have the following values:

0

(Default value) indicates that there is no accessibility information;

1

indicates that this trip can be used by a wheelchair (if the stop is also accessible);

2

wheelchair boarding is not possible for this trip.

routes

A list of route objects of routes passing by this stop. Please note that you can have more routes than departures: all routes are returned, even if there is no departures for this given route for the given date. See route list web-service call for more info on fields.

stop

Information on the given stop. Please see stop list web-service for more info on fields.

/ws/realtime/vehicles/{feedKey}

Request parameters

routeId

The ID of the route you want to request vehicles info. If missing, return vehicles for all routes.

Response

A list of VehiclePosition objects currently active. JSON example:

{
    "feedTimestamp": 1570209110485,
    "timestamp": 1570450612875,
    "vehiclePositions": [
        {
            "bearing": -143.09293,
            "latitude": -43.234,
            "longitude": -12.34,
            "odometerMeters": 8765.43,
            "stopId": "TC-6",
            "stopSeq": 2,
            "stopStatus": "IN_TRANSIT_TO",
            "timestamp": 1570450607000,
            "tripId": "CS-4567",
            "routeId": "O1",
            "vehicleId": "Eagle"
        },
        ...
    ]
}
feedTimestamp

The timestamp of the static data, as returned in the feed-info endpoint. If this timestamp changes, you should probably update any cached values on the client side (for example, a list of stops or routes kept in cache).

timestamp

Timestamp of the vehicle position feed. This can be used as a default value for individual vehicle position timestamps, if they are not provided.

vehicleId

Mandatory. Unique internal identifier of the vehicle.

timestamp

Mandatory. Timestamp of the real-time data (timestamp of the latest acquisition time).

label, licensePlate

Both optional. Human-readable label and licence plate number of the vehicle.

tripId

Optional. ID of the trip the vehicle is actually running.

stopId

Optional. ID of the current stop the vehicle is stopped at, or the next stop the vehicle is aiming to.

stopSeq

Optional. Stop sequence in the trip of the stop. Present only if stopId is present.

stopStatus

Optional. Status of the current/next stop: INCOMING_AT, STOPPED_AT or IN_TRANSIT_TO.

latitude, longitude

Mandatory. WGS84 geographical coordinates of the vehicle.

bearing

Optional. Bearing of the direction of travel, in degree, of the vehicle.

odometerMeters

Optional. The odometer value, in meters, in the current trip, of the vehicle.

speedMps

Optional. Speed of the vehicle, in meter per seconds.

/ws/alerts/active/{feedKey}

Request parameters

preferredLang

ISO 639-1 two-letters language code to select the returned alert data preferred language. Please note that in case the preferred language is not available as translation on the server, the alert title and description will be returned with a default language. Default to “en”. Optional.

sortStops

If set to “true”, will try to sort stops in their “natural” order in the output list. Do not enable this option if it’s not necessary as it can potentially make the API slower. Default to “false”. Optional.

channel

Alert channel to use for returning data. Check with us for possible configured values.

Response

A list of transitAlerts objects active for the given date/time range. JSON example:

[
    {
        "activeFrom": "2001-01-08T00:00:00Z",
        "agencies": [],
        "apiPublication": {
            "dateTime": "2019-07-05T10:35:00Z"
        },
        "cause": "CONSTRUCTION",
        "description": "Due to public work (crater erasure), routes CS will not be running starting from Tycho (Brah\u00e9) Central.",
        "effect": "REDUCED_SERVICE",
        "formattedActiveRange": "From Jan 8, 2001",
        "id": "4356",
        "lang": "en",
        "lastUpdated": "2019-07-08T06:05:32Z",
        "level": 2,
        "publishActiveRange": true,
        "routes": [
            {
                "agencyId": "moon-rail",
                "id": "01",
                "longName": "Clavius - Seleucus",
                "shortName": "CS",
                "color": "AE6F09",
                "textColor": "FFFFFF",
                "type": 3,
                "group": "rail",
                "direction0Name": "Clavius",
                "direction1Name": "Seleucus",
                "fromDate": "2019-07-01T00:00:00Z",
                "toDate": "2020-07-03T00:00:00Z",
            }
        ],
        "splitActiveRange": false,
        "stops": [
            {
                "id": "TC-3",
                "latitude": -43.31,
                "longitude": -11.36,
                "name": "Tycho Central",
                "parentId": "TC",
                "type": 0,
                "wheelchairBoarding": 0
            }
        ],
        "title": "Crater erasure - route CS truncated at Tycho Central"
    },
    ...
]
transitAlerts

A list of alerts, active in the given range.

id

Internal unique ID of the alert. This ID is reused in the optional alerts fields for each departure.

level

Level of the alert:

1

Informational message;

2

Warning alert;

3

Critical alert.

lang

ISO 639-1 two-letters language code in which title and description are written for. This lang could be different from the preferredLang given as parameter.

title

Title in text format of the alert. Usually a short summary which can be displayed as an header. Note that this field may be missing (empty) and you should handle this case gracefully. Optional.

description

Full description in text format of the alert (optional). This description fully describe the alert and can be quite long.

activeFrom, activeTo

UTC ISO 8601 active from/to date/time range. Both are optional: you can thus get an activeTo w/o from, the other way around, both or none. Example: 2015-06-23T22:00:00Z (Z is for Zero meridian, UTC).

publishActiveRange

Boolean value. If the active range should be displayed to the user, false otherwise.

splitActiveRange

Boolean value. If false (the default), the active from/to date/time range is continuous. If true, the range should be split according to the hour part, if the date range is longer than 2 days. For example: from = Jan 2, 6 PM; to = Jan 3, 10 PM. In split mode (splitActiveRange is true), the alert is active from 6 PM to 10 PM every day from Jan 2 to Jan 3 (here two intervals). In non-split mode (splitActiveRange is false), the alert is active from Jan 2, 6 PM to Jan 3, 10 PM (one interval). In split mode, if the end hour is less than the start hour, the hour interval span over midnight. For example: from = Jan 2, 10 PM; to = Jan 4, 4 AM. In split mode, the alert is active from 10 PM to 4 AM every night from Jan 2 to Jan 4 (here two nights). In non-split mode, the alert is active from Jan 2, 10 PM to Jan 4, 4 AM. For hour computation, please use local timezone, as this can impact ranges spanning DST dates.

formattedActiveRange

Formatted active range in the language defined by the request parameter “preferredLang”, such as (in French): À partir du 2 nov. 2015 .

agencies

Optional list of agencies this alert is active for. An alert active for an agency is considered as a “global alert” and should be displayed as such in a client application (for example in a main screen).

routes

Optional list of routes this alert is active for. If no route are selected for this alert, the list of routes passing by selected stops are output instead.

routes/direction

Optional field, present if the route is only impacted for a given direction. If this field is not present, the route is impacted for both directions.

stops

Optional list of stops this alert is active for.

cause

Cause of the alert. Possible choices: UNKNOWN_CAUSE (1), OTHER_CAUSE (2), TECHNICAL_PROBLEM (3), STRIKE (4), DEMONSTRATION (5), ACCIDENT (6), HOLIDAY (7), WEATHER (8), MAINTENANCE (9), CONSTRUCTION (10), POLICE_ACTIVITY (11), MEDICAL_EMERGENCY (12).

effect

Effect of the alert. Possible choices: NO_SERVICE (1), REDUCED_SERVICE (2), SIGNIFICANT_DELAYS (3), DETOUR (4), ADDITIONAL_SERVICE (5), MODIFIED_SERVICE (6), OTHER_EFFECT (7), UNKNOWN_EFFECT (8), STOP_MOVED (9). The value “NO_SERVICE” has a special meaning and imply that there is no service at all on the impacted elements (routes and/or stops).

apiPublication, channel1Publication

A list of UTC timestamp when the alert should start to be displayed for each channel.

Note

Please note that the semantics of having routes and/or stops in an alert is a bit complex. Here is the meaning for various cases:

some agencies, and anything else

The alert is a “global” alert for the whole agency network.

some routes but no stops

The alert is applicable for all given routes for the whole of their range.

some stops but no routes

The alert is applicable for all given stops, for all routes passing by.

both stops and routes

The alert is applicable for all given stops, only for the given routes. (the resulting set is the intersection of the stop and route sets).

/ws/layer/kml/feed/{feedKey}

Request parameters

includeStops

Set to true or false whether you want to include stops in the answer. Only stops for hop end-points are returned. All stops are stored in a dedicated folder. True by default.

includeRoute

Set to true or false whether you want to include route geometry in the answer. Route geometry segments are stored in a dedicated folder. True by default.

routeId

Optional. If provided, filter the result for the provided route ID only. If no route matches, return an empty KML.

aggregateByStation

If set to true , only stations (or stops w/o station) are returned in the result. Please note that this may end-up in less precise geometry being returned, as the geometry segment end-points will be snapped to the station location, which can be at a different place than the original stop location. False by default.

ignoreUndefinedGeometry

If set to true , do no return geometry segments which are undefined. If this option is not activated, an undefined segment will be returned as a straight-line between the two end-stops. Activating this option may result in a partial route geometry being returned. Default to false.

pruneRedundant

If set to true , prune some redundant geometry. Be careful, as the redundant geometry pruning algorithm may lead to imprecise geometry being returned. A redundant geometry is a geometry segment between two stops that have an alternate path which is not too long vs the original. (For example a segment [AC] may be marked as redundant if both geometry [AB] and [BC] are defined). Default to false.

usagePruneThreshold

A floating-point threshold value between 0 and 1. All segments whose usage is below this value are not returned. The usage factor of a segment (between 0 and 1) is the load factor in trip.days compared to the max value for the route. For example if the route has a max usage of 1000 trip.days and a segment 300, the segment usage is 0.3. This option can be useful to trim less often used portion of a route, and only return the most important sections. Be careful, as this option may lead to an unconnected geometry being returned in some cases. Default to 0.

from, to

A date in the format YYYY-MM-DD , for example 2016-11-23 . Filter out segments which are used only outside of the provided range. A single date can be provided, for example only providing from will filter out segments which are only used before the provided date. Please note that only one date range is computed for each segment. A segment that is used only in June and September for example, will thus be returned if the from-to range is July-August. Please note that those dates are both logical dates (a trip running at 2AM is usually included in the previous logical day). Default to no filtering (null).

includeUsage

Include in the answer the usage (load factor) of each segment. Please see above for the definition of a segment usage.

Response

A standard KML file, with one or two folders (stops, route geometry).


End of document.