Created
November 16, 2015 12:42
-
-
Save stevage/7e4fb6e9bc96f7d73039 to your computer and use it in GitHub Desktop.
PTV realtime API swagger YAML
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| swagger: '2.0' | |
| # This is your document metadata | |
| info: | |
| version: "2.1.0" | |
| title: PTV Timetable API (community portal) | |
| description: | | |
| This is Open Knowledge Australia's version of Public Transport Victoria's <a href="https://www.data.vic.gov.au/data/dataset/ptv-timetable-api">Timetable API</a> documentation, built with [Swagger](https://github.com/swagger-api/swagger-ui). It was created by <a href="http://stevebennett.me">Steve Bennett</a> ([email protected], <a href="https://twitter.com/stevage1">@stevage1</a>) for Open Knowledge Australia. It was not funded or supported by PTV, but was based on the official documentation using the CC-BY licence. | |
| The Timetable API 2.0.0 lets you find stations and stops in a given area, query the next few departures from a stop, and the stops on a given line or service. Version 2.1.0, released on 28 May 2015 adds realtime stop arrivale times for trams and some buses, and disruption data. It does not provide vehicle location tracking, spatial data other than stop locations, or route planning. PTV's documentation remains the definitive source. Report issues in this documentation in [GitHub](https://github.com/OKFNau/PTV-API-Swagger/issues). | |
| ##Related tools | |
| * [Additional PTV reference material](https://ptv.vic.gov.au/about-ptv/ptv-data-and-reports/digital-products/ptv-timetable-api/) | |
| * Libraries: | |
| * [PyPtv advanced Python library](https://github.com/jessexoc/pyptv) by Jesse O'Connor (supports API 2.1.0) | |
| * [PtvPy simple Python wrapper](https://github.com/stevage/ptvpy) by Steve Bennett (API 2.0.0) | |
| * [Test harness for PHP](https://github.com/wongm/ptv-api-php-test-harness) by Marcus Wong | |
| * [.NET Portable Class Library in C#](https://github.com/Readify/ptv) by Mitch Denny (Readify) | |
| * [Qt library in C++](https://github.com/loomiverse/ptv-api-qt), by Dennis Weaver | |
| * [Objective C library](https://github.com/loomiverse/ptv-api-objectivec), by Dennis Weaver | |
| * [JavaScript - basic code](https://github.com/OKFNau/PTV-API-Swagger/blob/gh-pages/dist/api-signature.js) by Steve Bennett | |
| * [OpenTripPlanner with PTV data](https://github.com/loomiverse/ptv-otp-build) by Dennis Weaver | |
| * [Previous non-Swagger version of this documentation](http://stevage.github.io/PTV-API-doc/) by Steve Bennett | |
| * Sample code: | |
| * [Sample code for C#, Java, Objective C](http://stevage.github.io/PTV-API-doc/#header29) (from official documentation) | |
| * [PTVGlass ](https://github.com/longzheng/PTVGlass) (C#) by Long Zheng | |
| ##Related data | |
| * [PTV timetable data in GTFS format](https://www.data.vic.gov.au/data/dataset/ptv-timetable-and-geographic-information-2015-gtfs) - a complete bulk download of the timetable for 2 weeks | |
| * [PTV spatial data in GeoJSON format](https://github.com/okfnau/opentransportdata): Bus routes & stops, tram routes, stops & centrelines; train routes, corridor centrelines, track centrelines, stations, platforms, car parks and bicycle parking. | |
| * PTV Usage data on data.vic.gov.au: | |
| * [Bus Boardings and Alightings](https://www.data.vic.gov.au/data/dataset/bus-boardings-and-alightings-at-bus-stops-new) | |
| * [Tram Boardings and Alightings](https://www.data.vic.gov.au/data/dataset/tram-boardings-and-alightings-at-tram-stops-2015) | |
| * [Tram Average Load by Surveyed Service](https://www.data.vic.gov.au/data/dataset/tram-average-load-by-surveyed-service) | |
| * [Metro Train Loads at Cordon Stations](https://www.data.vic.gov.au/data/dataset/may-2012-melbourne-metro-train-loads-by-service-at-cordon-stations-new) | |
| * PTV Accessibility data (not all machine readable): | |
| * [Accessible toilets](http://ptv.vic.gov.au/getting-around/accessible-transport/accessible-trains/accessible-toilets-at-metropolitan-stations/) | |
| * [Station patronage (.xls)](http://ptv.vic.gov.au/assets/PTV/PTV%20docs/research/PTV-Station-by-Station-Fact-Sheet-accessible-version.xls) | |
| * [Bus patronage](http://ptv.vic.gov.au/assets/PTV/PTV%20docs/research/PTV-Bus-Route-Patronage-Summary-accessible-version.xls) | |
| * [Passenger load surveys](http://ptv.vic.gov.au/about-ptv/ptv-data-and-reports/passenger-load-surveys/) | |
| * [TramTracker API](http://ws.tramtracker.com.au/pidsservice/pids.asmx) (SOAP) | |
| * [Melbourne bike share API](http://www.melbournebikeshare.com.au/stationmap/data) (or use [CityBik.es](http://api.citybik.es/v2/) ) | |
| ##Licence | |
| [Creative Commons 3.0 Attribution](https://creativecommons.org/licenses/by/3.0/au/) (Attribute "Public Transport Victoria" and "Steve Bennett") | |
| license: | |
| url: https://creativecommons.org/licenses/by/3.0/au/ | |
| name: Creative Commons Attribution 3.0 Australia | |
| termsOfService: | | |
| The data provided to you by PTV is provided 'as is' and PTV is not liable for how you use this data, how third parties use or rely on this data or any errors contained within the data. You are responsible for determining whether the data is suitable for your particular usage and purposes. | |
| Do use the API dynamically to get the most up-to-date data for your audience. | |
| Do not cache the data. | |
| Do not hammer our servers. Do not use the API to make multiple requests for large sets of data in short periods of time. | |
| host: timetableapi.ptv.vic.gov.au | |
| schemes: | |
| - http | |
| #basePath: /v2 | |
| produces: | |
| - application/json | |
| definitions: | |
| flags: | |
| type: string | |
| description: > | |
| Hyphen (-) separated list of stop options. | |
| RR = Reservations Required; | |
| GC = Guaranteed Connection; | |
| DOO = Drop Off Only; | |
| PUO = Pick Up Only; | |
| MO = Mondays only; | |
| TU = Tuesdays only; | |
| WE = Wednesdays only; | |
| TH = Thursdays only; | |
| FR = Fridays only; | |
| SS = School days only; | |
| note: ignore "E" flag | |
| cluster: | |
| type: object | |
| properties: | |
| locations: | |
| type: array | |
| items: | |
| $ref: "#/definitions/location" | |
| required: [ locations ] | |
| searchresult: | |
| type: object | |
| required: [ type, result ] | |
| properties: | |
| type: | |
| type: "string" | |
| description: "'stop' or 'line'" | |
| result: | |
| description: | | |
| Stops have transport_type, suburb, location_name, lat, lon, distance, stop_id. | |
| Lines have transport_type, line, line_name, line_number | |
| $ref: "#/definitions/line_or_stop" | |
| transport_type: | |
| type: string | |
| description: "(stop only) the mode of transport serviced by the stop: `train`, `tram`, `bus`, `vline`, `nightrider`" | |
| lat: | |
| description: latitude in decimal degrees, eg -37.82005 | |
| type: number | |
| example: -37.82005 | |
| lon: | |
| description: longitude in decimal degrees, eg 144.959047 | |
| type: number | |
| example: 144.959047 | |
| stop_id: | |
| type: integer | |
| description: the unique identifier of each stop | |
| location_name: | |
| type: string | |
| description: the name of the stop based on a concise geographic description. e.g. "20-Barkly Square/115 Sydney Rd (Brunswic | |
| suburb: | |
| type: string | |
| description: Suburb name | |
| distance: | |
| type: number | |
| description: Returns zero. "It is a legacy attribute of unknown worth" | |
| location: | |
| type: object | |
| properties: | |
| suburb: | |
| $ref: "#/definitions/suburb" | |
| location_name: | |
| $ref: "#/definitions/location_name" | |
| lat: | |
| $ref: "#/definitions/lat" | |
| lon: | |
| $ref: "#/definitions/lon" | |
| distance: | |
| $ref: "#/definitions/distance" | |
| transport_type: | |
| $ref: "#/definitions/transport_type" | |
| stop_id: | |
| $ref: "#/definitions/stop_id" | |
| outlet_type: | |
| type: string | |
| description: "(outlet only) either `stop` meaning a myki card machine at a station or stop or `retail` meaning a shop of some kind" | |
| required: [ suburb, location_name, lat, lon, distance, transport_type, stop_id, outlet_type ] | |
| line_or_stop: | |
| type: object | |
| required: [ transport_type ] | |
| properties: | |
| transport_type: | |
| $ref: "#/definitions/transport_type" | |
| suburb: | |
| $ref: "#/definitions/suburb" | |
| location_name: | |
| $ref: "#/definitions/location_name" | |
| lat: | |
| $ref: "#/definitions/lat" | |
| lon: | |
| $ref: "#/definitions/lon" | |
| distance: | |
| $ref: "#/definitions/distance" | |
| stop_id: | |
| $ref: "#/definitions/stop_id" | |
| line_id: | |
| $ref: "#/definitions/line_id" | |
| line_name: | |
| $ref: "#/definitions/line_name" | |
| line_number: | |
| $ref: "#/definitions/line_number" | |
| stop: # ideally merge with 'location' | |
| type: object | |
| properties: | |
| suburb: | |
| $ref: "#/definitions/suburb" | |
| location_name: | |
| $ref: "#/definitions/location_name" | |
| lat: | |
| $ref: "#/definitions/lat" | |
| lon: | |
| $ref: "#/definitions/lon" | |
| distance: | |
| $ref: "#/definitions/distance" | |
| transport_type: | |
| $ref: "#/definitions/transport_type" | |
| stop_id: | |
| $ref: "#/definitions/stop_id" | |
| required: [ suburb, location_name, lat, lon, distance, stop_id ] | |
| example: | |
| result: | |
| suburb: East Melbourne | |
| transport_type: tram | |
| stop_id: 2825 | |
| location_name: "Clarendon St/Wellington Pde #11" | |
| lat: -37.81603 | |
| lon: 144.9824 | |
| distance: 4.08647838e-06 | |
| #type: stop | |
| line_id: | |
| type: string | |
| description: (numeric string) the unique identifier of each line | |
| example: 1818 | |
| line_name: | |
| type: string | |
| description: the name of the line. | |
| example: "970 - City - Frankston - Mornington - Rosebud via Nepean Highway & Frankston Station" | |
| line_number: | |
| type: string | |
| description: the line number that is presented to the public (i.e. not the "line_id") | |
| line: | |
| type: object | |
| properties: | |
| transport_type: | |
| $ref: "#/definitions/transport_type" | |
| line_id: | |
| $ref: "#/definitions/line_id" | |
| line_name: | |
| $ref: "#/definitions/line_name" | |
| line_number: | |
| $ref: "#/definitions/line_number" | |
| required: [ transport_type, line_id, line_name, line_number] | |
| direction: | |
| type: object | |
| properties: | |
| linedir_id: | |
| type: integer | |
| description: unique identifier of a particular line and direction. e.g. "21" | |
| direction_id: | |
| type: integer | |
| description: unique identifier of a direction (e.g. "0" signifies "city") | |
| direction_name: | |
| type: string | |
| description: name of the direction of the service. e.g. "City (Flinders Street)" | |
| line: | |
| $ref: "#/definitions/line" | |
| required: [ linedir_id, direction_id, direction_name, line ] | |
| platform: | |
| type: object | |
| properties: | |
| realtime_id: | |
| type: integer | |
| description: a place holder for the stop's real-time feed system ID (for potential future implementation; as no real-time feeds are provided at this time, this returns "0") | |
| stop: | |
| $ref: "#/definitions/stop" | |
| direction: | |
| $ref: "#/definitions/direction" | |
| required: [ realtime_id, stop, direction ] | |
| run: | |
| type: object | |
| properties: | |
| transport_type: | |
| $ref: "#/definitions/transport_type" | |
| run_id: | |
| type: integer | |
| description: The unique identifier of the run | |
| num_skipped: | |
| type: integer | |
| description: | | |
| The number of stops skipped for the run, applicable to train; a number greater than zero indicates either a | |
| limited express or express service | |
| destination_id: | |
| type: integer | |
| description: The stop_id of the destination, i.e. the last stop for the run | |
| example: 1044 | |
| destination_name: | |
| type: string | |
| description: The location_name of the destination, i.e. the last stop for the run | |
| example: "Craigieburn" | |
| required: [ transport_type, run_id, num_skipped, destination_id, destination_name ] | |
| timetable_value: | |
| type: object | |
| properties: | |
| time_table_utc: | |
| type: string | |
| format: date-time | |
| description: the scheduled time of the service at the stop, in ISO 8601 UTC | |
| example: "2014-11-18T03:21:00Z" | |
| time_realtime_utc: | |
| type: string | |
| format: date-time | |
| description: the real-time of the service at the stop if this is available, in ISO 8601 UTC. Available for trams and some bus routes; if the relevant feed system is not available, it will return null | |
| example: "2014-11-18T03:24:00Z" | |
| flags: | |
| $ref: "#/definitions/flags" | |
| platform: | |
| $ref: "#/definitions/platform" | |
| run: | |
| $ref: "#/definitions/run" | |
| required: [ time_table_utc, time_realtime_utc, flags , platform, run ] | |
| disruptions: | |
| type: array | |
| items: | |
| $ref: "#/definitions/disruption" | |
| disruption: | |
| type: object | |
| required: [ title, url, description, publishedOn ] | |
| properties: | |
| title: | |
| type: string | |
| description: a headline or title summarising the disruption information | |
| example: "Buses replacing trains on the Cranbourne and Pakenham lines after 8.45pm: Saturday 15 February 2014" | |
| url: | |
| type: string | |
| description: the url of the relevant article on the PTV website | |
| example: http://ptv.vic.gov.au/disruptions/buses-replacing-trains-on-thecranbourne-and-pakenham-lines-after-8-45pm-saturday-15-february-2014/ | |
| description: | |
| type: string | |
| description: a truncated version of the description of the disruption that appears on the PTV website | |
| example: "Due to signalling upgrades and construction work as part of the Springvale Level Crossing Removal, buses will replace all trains between Westall and Dandenong after 8.45pm on Saturday 15 February." | |
| publishedOn: | |
| type: string | |
| format: date-time | |
| description: the date and time the disruption information is published on the PTV website, in ISO 8601 UTC format | |
| example: “2014-01-29T23:30:54Z | |
| departures: | |
| title: Departures | |
| type: object | |
| required: [ values ] | |
| properties: | |
| values: | |
| type: array | |
| items: | |
| $ref: "#/definitions/timetable_value" | |
| example: | |
| - platform: | |
| realtime_id: 0 | |
| stop: | |
| suburb: East Melbourne | |
| transport_type: train | |
| stop_id: 1104 | |
| location_name: Jolimont-MCG | |
| lat: -37.81653 | |
| lon: 144.9841 | |
| distance: 0 | |
| direction: | |
| linedir_id: 41 | |
| direction_id: 8 | |
| direction_name: Hurstbridge | |
| line: | |
| transport_type: train | |
| line_id: 8 | |
| line_name: Hurstbridge | |
| line_number: Hurstbridge | |
| run: | |
| transport_type: train | |
| run_id: 21172 | |
| num_skipped: 0 | |
| destination_id: 1041 | |
| destination_name: Clifton Hill | |
| time_timetable_utc: 2014-01-20T03:21:00Z | |
| time_realtime_utc: null | |
| flags: | |
| parameters: | |
| devid: | |
| name: devid | |
| in: query | |
| type: integer | |
| required: true | |
| description: Your developer ID, provided by PTV. | |
| signature: | |
| name: signature | |
| in: query | |
| type: string | |
| required: true | |
| description: Computed HMAC signature. See HealthCheck implementation notes. | |
| latitude: | |
| name: latitude | |
| in: path | |
| type: number | |
| required: true | |
| description: | | |
| prescribed latitude, in decimal degrees. | |
| e.g. `-37.8` | |
| longitude: | |
| name: longitude | |
| in: path | |
| type: number | |
| required: true | |
| description: | | |
| prescribed longitude, in decimal degrees. e.g. `144.9` | |
| mode: | |
| name: mode | |
| in: path | |
| type: string | |
| required: true | |
| description: | | |
| A number as follows: | |
| * `0` Train (metropolitan) | |
| * `1` Tram | |
| * `2` Bus (metropolitan and regional, but not V/Line) | |
| * `3` V/Line train and coach | |
| * `4` NightRider | |
| stop: | |
| name: stop | |
| type: string | |
| in: path | |
| required: true | |
| description: the `stop_id` of the stop | |
| line: | |
| name: line | |
| type: string | |
| in: path | |
| required: true | |
| description: the `line_id` of the requested services | |
| stoplimit: | |
| name: limit | |
| type: integer | |
| in: path | |
| required: true | |
| description: | | |
| The number of next departure times to be returned, i.e. `5` will return the next five | |
| departure times (notes: `0` will return departures for the entire day; `1` will limit | |
| it to the very next departure, even if this is a few days away) | |
| for_utc: | |
| name: for_utc | |
| type: string | |
| format: date-time | |
| in: query | |
| required: false | |
| description: Get services from this date/time and later, in ISO 8601 UTC format | |
| paths: | |
| /v2/healthcheck: | |
| get: | |
| summary: Health Check | |
| tags: [ General ] | |
| description: | | |
| A check on the timely availability, connectivity and reachability of the services that deliver security, caching and data to web clients. A health status report is returned. | |
| ### Signature | |
| Every API call, including this one, requires a "signature" parameter. This is an | |
| uppercase HMAC-SHA1 hash of the whole request, computed as `crypto.HMACSHA1(request,key).toUppercase()`, where: | |
| * `request` is the URL from `/v2` up to and including the `devid=` parameter | |
| * `key` is your private API key | |
| parameters: | |
| - name: timestamp | |
| in: query | |
| type: string | |
| format: date-time | |
| required: true | |
| description: the date and time of the request in ISO 8601 UTC format<br/> e.g. `2013-11-13T05:24:25Z`. | |
| - $ref: "#/parameters/devid" | |
| - $ref: "#/parameters/signature" | |
| responses: | |
| 200: | |
| description: Successful response | |
| schema: | |
| title: HealthCheckResponse | |
| type: object | |
| properties: | |
| securityCheckOk: | |
| type: boolean | |
| description: indicates whether your key is valid/signature is calculated correctly | |
| clientClockOk: | |
| type: boolean | |
| description: indicates whether your clock is synchronised with our clock within 3 minutes | |
| memCacheOK: | |
| type: boolean | |
| description: indicates status of the performance cache | |
| databaseOK: | |
| type: boolean | |
| description: indicates availability of the data | |
| /v2/nearme/latitude/{latitude}/longitude/{longitude}: | |
| get: | |
| summary: Stops Nearby | |
| description: | | |
| Stops Nearby returns up to 30 stops nearest to a specified coordinate. "Stops" includes train stations as well as tram and bus stops. | |
| There are no spatial constraints on how Stops Nearby retrieves stops. It will always return up to 30 stops near the passed latitude and longitude coordinates, even if some of those stops are (relatively) far away. | |
| tags: [ Search ] | |
| parameters: | |
| - $ref: "#/parameters/latitude" | |
| - $ref: "#/parameters/longitude" | |
| - $ref: "#/parameters/devid" | |
| - $ref: "#/parameters/signature" | |
| responses: | |
| 200: | |
| description: Successful response | |
| schema: | |
| title: Stops nearby | |
| type: array | |
| items: | |
| $ref: "#/definitions/stop" | |
| /v2/poi/{poi}/lat1/{latitude1}/long1/{longitude1}/lat2/{latitude2}/long2/{longitude2}/griddepth/{griddepth}/limit/{limit}: | |
| get: | |
| summary: Transport POIs by Map | |
| tags: [ Search ] | |
| description: | | |
| Transport POIs by Map returns a set of locations consisting of stops and/or myki ticket outlets (collectively known as points of interest – i.e. POIs) within a region demarcated on a map through a set of latitude and longitude coordinates. | |
| Through the poi parameter, the API can return any combination of POIs (e.g. ticket outlets only, bus stops only, tram stops and ticket outlets only, all of the above, and so on). | |
| Where POIs are geographically dispersed they are returned in a list; where they are geographically concentrated they can be returned in a cluster, depending on the map griddepth that is sent in the request. | |
| Have a play around with the `griddepth` parameter to see what best suits the device you are developing for. If you set griddepth to zero it will not cluster. | |
| You can also set a limit of how many stops are listed in a cluster. The API will return what the total number of POIs is, however it will only return data for as many POIs are set by the `limit`. | |
| When there are more POIs in a cluster than the `limit`, the POIs returned will be determined by a business rule that is hard coded at the server end. The order of priority is V/Line stops first, followed by train, tram, bus, NightRider and, last of all, ticket outlets. | |
| ### Response | |
| Returns a list of JSON objects which are either `locations` or `clusters`; `clusters` have their own list of `locations` within them. `locations` have either a `stop` or `outlet` (i.e. ticket outlet) object embedded within them. For more information on the data structures, check out the JSON object structure. | |
| parameters: | |
| - name: poi | |
| type: string | |
| description: | | |
| a comma separated list of numbers representing the types of POIs you want returned, defined as follows: | |
| * `0` Train (metropolitan) | |
| * `1` Tram | |
| * `2` Bus (metropolitan and regional, but not V/Line) | |
| * `3` V/Line regional train and coach | |
| * `4` NightRider | |
| * `100` Ticket outlet | |
| e.g. `0,1,2,4,100` would return train, tram, bus, NightRider & ticket outlets | |
| in: path | |
| required: true | |
| - name: latitude1 | |
| type: number | |
| description: northern latitude of the bounding box, expressed in decimal degrees. | |
| in: path | |
| required: true | |
| - name: latitude2 | |
| type: number | |
| description: southern latitude of the bounding box, expressed in decimal degrees. | |
| in: path | |
| required: true | |
| - name: longitude1 | |
| type: number | |
| description: western longitude of the bounding box, expressed in decimal degrees. | |
| in: path | |
| required: true | |
| - name: longitude2 | |
| type: number | |
| description: eastern longitude of the boounding box, expressed in decimal degrees. | |
| in: path | |
| required: true | |
| - name: griddepth | |
| type: integer | |
| description: the number of cells per block of cluster grid (0-20 inclusive). | |
| in: path | |
| required: true | |
| - name: limit | |
| type: integer | |
| description: the minimum number of POIs (stops or outlets) required to create a cluster, as well as the maximum number of POIs returned as part of a cluster in the JSON response (for example, if the limit is "4", at least 4 POIs are required to form a cluster; and in the JSON response, if there are 7 total locations in a cluster, only 4 will be listed in the response) | |
| in: path | |
| required: true | |
| - $ref: "#/parameters/devid" | |
| - $ref: "#/parameters/signature" | |
| responses: | |
| 200: | |
| description: "" | |
| schema: | |
| title: Success | |
| type: object | |
| # Seems to match the sample response, if not the text. Unclear if clusters has any elements other than the array. | |
| properties: | |
| minLat: | |
| type: number | |
| description: the minimum latitude value of all of the locations in the cluster, including those that are not returned (i.e. they are beyond the limit set) | |
| minLong: | |
| type: number | |
| description: the minimum longitude value of all of the locations in the cluster, including those that are not returned (i.e. they are beyond the limit set) | |
| maxLat: | |
| type: number | |
| description: the maximum latitude value of all of the locations in the cluster, including those that are not returned (i.e. they are beyond the limit set) | |
| maxLong: | |
| type: number | |
| description: the maximum longitude value of all of the locations in the cluster, including those that are not returned (i.e. they are beyond the limit set) | |
| weightedLat: | |
| type: number | |
| description: latitude at the point that is the average of all POIs returned in a grid cell | |
| weightedLong: | |
| type: number | |
| description: longitude at the point that is the average of all POIs returned in a grid cell | |
| totalLocations: | |
| type: integer | |
| description: the total number of locations within the region described | |
| locations: | |
| type: array | |
| description: | | |
| "locations" have either a "stop" or "outlet" (i.e. ticket outlet) object embedded within them. | |
| items: | |
| - $ref: "#/definitions/location" | |
| clusters: | |
| type: array | |
| description: | | |
| "clusters" have their own list of "locations" within them | |
| items: | |
| - $ref: "#/definitions/cluster" | |
| required: [ minLat, minLong, maxLat, maxLong, weightedLat, weightedLong, totalLocations, clusters, locations ] | |
| example: | |
| minLat: -37.81959 | |
| minLong: 144.979126 | |
| maxLat: -37.8157463 | |
| maxLong: 144.9854 | |
| weightedLat: -37.81671 | |
| weightedLong: 144.982849 | |
| totalLocations: 7 | |
| locations: | |
| - suburb: Melbourne City | |
| transport_type: tram | |
| stop_id: 2171 | |
| location_name: 7B-Rod Laver Arena/Melbourne Park | |
| lat: -37.81959 | |
| lon: 144.979126 | |
| distance: 0 | |
| /v2/search/{searchtext}: | |
| get: | |
| summary: Search | |
| tags: [ Search ] | |
| description: | | |
| The Search API returns all stops and lines that match the input search text. | |
| Note: It will only return “line” objects if the input search text is less than three (3) characters. | |
| ### Response | |
| Returns an array of JSON "result" objects for which the `type` equals either `stop` or `line`. | |
| A `stop` object or `line` object is embedded within each "result" depending on its type. | |
| parameters: | |
| - name: searchtext | |
| type: string | |
| description: | | |
| Search text that could match a stop or line, for example `Alamein` | |
| in: path | |
| required: true | |
| - $ref: "#/parameters/devid" | |
| - $ref: "#/parameters/signature" | |
| responses: | |
| 200: | |
| description: "" | |
| schema: | |
| title: Results | |
| type: array | |
| items: | |
| $ref: "#/definitions/searchresult" | |
| example: | |
| - type: line | |
| result: | |
| transport_type: tram | |
| line_id: 5313 | |
| line_name: Route 31 - Hoddle Street - Victoria Harbour Docklands | |
| line_number: Route 31 | |
| - type: "stop" | |
| result: | |
| suburb: East Melbourne | |
| transport_type: tram | |
| stop_id: 2825 | |
| location_name: "Clarendon St/Wellington Pde #11" | |
| lat: -37.81603 | |
| lon: 144.9824 | |
| distance: 4.08647838e-06 | |
| /v2/lines/mode/{mode}: | |
| get: | |
| summary: Lines by Mode | |
| tags: [ Search ] | |
| description: | | |
| Lines by Mode returns the lines for a selected mode of transport. | |
| **Note** Only one transport type can be queried at a time through the Lines by Mode API. | |
| **Note** The optional parameter `name` allows you to filter on a specific line. | |
| parameters: | |
| - $ref: "#/parameters/mode" | |
| - name: name | |
| description: | | |
| Part of a line’s name e.g. “Alamein”, “Highpoint” | |
| type: string | |
| in: query | |
| - $ref: "#/parameters/devid" | |
| - $ref: "#/parameters/signature" | |
| responses: | |
| 200: | |
| description: OK | |
| schema: | |
| title: Lines | |
| description: "List of lines matching the query" | |
| type: array | |
| items: | |
| $ref: "#/definitions/line" | |
| /v2/mode/{mode}/stop/{stop}/departures/by-destination/limit/{limit}: | |
| get: | |
| summary: Broad Next Departures | |
| tags: [ Timetable ] | |
| description: | | |
| Broad Next Departures returns the next departure times at a prescribed stop irrespective | |
| of the line and direction of the service. For example, if the stop is Camberwell Station, | |
| Broad Next Departures will return the times for all three lines (Belgrave, Lilydale and | |
| Alamein) running in both directions (towards the city and away from the city). | |
| Through the `limit` parameter you can choose to return the very next departure or all departures for the day from that point in time. | |
| ### Real-time data | |
| Results now include real-time data for tram and bus serviceswhere this data is made available to PTV. As at the date of this document, real-time data is available on all tram services in Melbourne. Work has also commenced to deliver real-time data for bus services in Melbourne; this work will continue progressively in metropolitan and regional Victoria. | |
| **No real-time data feeds are provided for services other than tram and bus.** | |
| We have implemented a throttling mechanism to protect our external suppliers of real-time data. As a result, the API may not return real-time tram and bus data in its response (all other data will continue to be made available). | |
| No real-time data is returned if the limit is set to `0` (zero). | |
| ** Note** The `for_utc` parameter is not documented in the official PTV documentation. | |
| ### Response | |
| Returns a collection of JSON timetable "values" that have a "platform" and "run" object | |
| embedded within them. The "platform" objects have a "stop" and "direction" object in | |
| them, and the "direction" object has a "line" object within it. | |
| parameters: | |
| - $ref: "#/parameters/mode" | |
| - $ref: "#/parameters/stop" | |
| - $ref: "#/parameters/stoplimit" | |
| - $ref: "#/parameters/for_utc" | |
| - $ref: "#/parameters/devid" | |
| - $ref: "#/parameters/signature" | |
| responses: | |
| 200: | |
| description: "" | |
| schema: | |
| title: Departures | |
| type: object | |
| required: [ values ] | |
| properties: | |
| values: | |
| type: array | |
| items: | |
| $ref: "#/definitions/timetable_value" | |
| example: | |
| - platform: | |
| realtime_id: 0 | |
| stop: | |
| suburb: East Melbourne | |
| transport_type: train | |
| stop_id: 1104 | |
| location_name: Jolimont-MCG | |
| lat: -37.81653 | |
| lon: 144.9841 | |
| distance: 0.0 | |
| direction: | |
| linedir_id: 38 | |
| direction_id: 5 | |
| direction_name: South Morang | |
| line: | |
| transport_type: train | |
| line_id: 5 | |
| line_name: South Morang | |
| line_number: South Morang | |
| run: | |
| transport_type: train | |
| run_id: 13975 | |
| num_skipped: 0 | |
| destination_id: 1224 | |
| destination_name: South Morang | |
| time_timetable_utc: 2014-01-20T03:21:00Z | |
| time_realtime_utc: null | |
| flags: "" | |
| /v2/mode/{mode}/line/{line}/stop/{stop}/directionid/{directionid}/departures/all/limit/{limit}: | |
| get: | |
| summary: Specific Next Departures | |
| tags: [ Timetable ] | |
| description: | | |
| Specific Next Departures returns the times for the next departures at a prescribed stop for | |
| a specific mode, line and direction. For example, if the stop is Camberwell Station, | |
| Specific Next Departures returns only the times for one line running in one direction (for | |
| example, the Belgrave line running towards the city). | |
| **See also** notes at Broad Next Departures. | |
| ### Response | |
| Returns a collection of JSON timetable "values" that have a "platform" and "run" object | |
| embedded within them. The "platform" objects have a "stop" and "direction" object in | |
| them, and the "direction" object has a "line" object within it. | |
| parameters: | |
| - $ref: "#/parameters/mode" | |
| - $ref: "#/parameters/line" | |
| - $ref: "#/parameters/stop" | |
| - name: directionid | |
| type: string | |
| in: path | |
| required: true | |
| description: the direction_id of the requested services | |
| - $ref: "#/parameters/stoplimit" | |
| - $ref: "#/parameters/for_utc" | |
| - $ref: "#/parameters/devid" | |
| - $ref: "#/parameters/signature" | |
| responses: | |
| 200: | |
| description: "" | |
| schema: | |
| $ref: "#/definitions/departures" | |
| /v2/mode/{GTFS_mode}/route_id/{GTFS_route}/stop/{GTFS_stop}/direction/{GTFS_direction}/departures/all/limit/{limit}: | |
| get: | |
| tags: [ Timetable ] | |
| summary: Specific Next Departures (GTFS Input) | |
| description: | | |
| The new Specific Next Departures (GTFS Input) API returns the same data as Specific Next Departures, namely the times for the next departures at a prescribed stop for a specific mode, line and direction. Unlike Specific next Departures, however, it uses data inputs from the PTV GTFS dataset. | |
| Results include real-time data for tram and bus services where this data is made available to PTV. | |
| **See also** notes at Broad Next Departures. | |
| The public transport data accessed through the PTV Timetable API and in the PTV GTFS dataset includes attributes with the same name that hold different data. For example, “stop_id” exists in both datasets but an API stop_id is different to a GTFS stop_id. | |
| Only the Specific Next Departures (GTFS Input) API uses the GTFS data – all other calls in the PTV Timetable API do not accept GTFS inputs. | |
| ### Response | |
| Returns an identical response to the Specific Next Departures API. | |
| **Note** The response will be PTV Timetable API JSON objects – not GTFS objects | |
| parameters: | |
| - name: GTFS_mode | |
| in: path | |
| type: string | |
| description: the GTFS servicemode of the stop, taken from the PTV GTFS dataset. GTFS service mode is defined in the PTV GTFS Release Notes available on the DataVic website. | |
| required: true | |
| - name: GTFS_route | |
| description: the GTFS route_id of the stop, taken from the PTV GTFS dataset e.g. “4-364-mjp-1”. Available within the trips.txt files. | |
| in: path | |
| type: string | |
| required: true | |
| - name: GTFS_stop | |
| description: The GTFS stop_id of the stop, taken from the PTV GTFS dataset e.g. “19943”. Available within the stop.txt files in the PTV GTFS dataset, | |
| in: path | |
| type: string | |
| required: true | |
| - name: GTFS_direction | |
| description: The GTFS direction_id of the stop, taken from the PTV GTFS dataset e.g. “0” Available within the trips.txt files. | |
| in: path | |
| type: string | |
| required: true | |
| - name: limit | |
| in: path | |
| type: integer | |
| required: true | |
| - $ref: "#/parameters/for_utc" | |
| - $ref: "#/parameters/devid" | |
| - $ref: "#/parameters/signature" | |
| responses: | |
| 200: | |
| description: "" | |
| schema: | |
| $ref: "#/definitions/departures" | |
| /v2/mode/{mode}/run/{run}/stop/{stop}/stopping-pattern: | |
| get: | |
| summary: Stopping Pattern | |
| tags: [ Timetable ] | |
| description: | | |
| The Stopping Pattern API returns the stopping pattern for a specific run (i.e. transport | |
| service) from a prescribed stop at a prescribed time. The stopping pattern is comprised of | |
| timetable values ordered by stopping order. | |
| ### Response | |
| Returns a collection of JSON timetable `values` that have a `platform` and `run` object | |
| embedded within them. The `platform` objects have a `stop` and `direction` object in | |
| them, and the `direction` object has a `line` object within it. | |
| ### Warning | |
| The `for_utc` parameter appears to be required. This is not documented. | |
| parameters: | |
| - $ref: "#/parameters/mode" | |
| - name: run | |
| type: string | |
| in: path | |
| required: true | |
| description: the run_id of the requested run | |
| - $ref: "#/parameters/stop" | |
| - $ref: "#/parameters/for_utc" | |
| - $ref: "#/parameters/devid" | |
| - $ref: "#/parameters/signature" | |
| responses: | |
| 200: | |
| description: "" | |
| schema: | |
| title: Stopping pattern | |
| type: object | |
| required: [ values ] | |
| properties: | |
| values: | |
| type: array | |
| items: | |
| $ref: "#/definitions/timetable_value" | |
| example: | |
| - platform: | |
| realtime_id: 0 | |
| stop: | |
| suburb: Melbourne City | |
| transport_type: train | |
| stop_id: 1071 | |
| location_name: Flinders Street | |
| lat: -37.81831 | |
| lon: 144.966965 | |
| distance: 0.0 | |
| direction: | |
| linedir_id: 0 | |
| direction_id: 8 | |
| direction_name: Hurstbridge | |
| line: | |
| transport_type: train | |
| line_id: 8 | |
| line_name: Hurstbridge | |
| line_number: Hurstbridge | |
| run: | |
| transport_type: train | |
| run_id: 21173 | |
| num_skipped: 0 | |
| destination_id: 0 | |
| destination_name: | |
| time_timetable_utc: 2014-01-20T03:19:00Z | |
| time_realtime_utc: null | |
| flags: | |
| /v2/mode/{mode}/line/{line}/stops-for-line: | |
| get: | |
| summary: Stops on a Line | |
| tags: [ Search ] | |
| description: | | |
| The Stops on a Line API returns a list of all the stops for a requested line, ordered by | |
| location name. | |
| ### Response | |
| Returns a collection of JSON "stop" objects ordered by `location_name` | |
| parameters: | |
| - $ref: "#/parameters/mode" | |
| - $ref: "#/parameters/line" | |
| - $ref: "#/parameters/devid" | |
| - $ref: "#/parameters/signature" | |
| responses: | |
| 200: | |
| description: | | |
| schema: | |
| title: Stops | |
| type: array | |
| items: | |
| $ref: "#/definitions/stop" | |
| example: | |
| - suburb: Plenty | |
| transport_type: bus | |
| stop_id: 28066 | |
| location_name: 200 Yan Yean Rd | |
| lat: -37.6616554 | |
| lon: 145.124359 | |
| distance: 0 | |
| /v2/disruptions/modes/{modes}: | |
| get: | |
| summary: Disruptions | |
| tags: [ General ] | |
| description: | | |
| The Disruptions API returns information on planned and unplanned disruptions for selected modes of transport. | |
| **Note** The disruption information provided is the same information that is made available by PTV through its digital channels; it is not an exhaustive list of all disruptions affecting public transport. | |
| ### Response | |
| Returns a list of JSON mode objects – i.e. objects named after the possible transport modes | |
| which are passed: a `general` object, a `metro-bus` object, a `metro-train` object, a `metro-tram` | |
| object, a `regional-bus` object, a `regional-coach` object and a `regional-train` object. | |
| Each of these mode objects has a collection of disruption information objects within it (or, it | |
| may be empty if there is no disruption information at the time of the request). | |
| parameters: | |
| - name: modes | |
| in: path | |
| type: string | |
| description: | | |
| A comma separated list of modes of transport for which disruption information is returned; possible values are: | |
| general | |
| metro-bus | |
| metro-train | |
| metro-tram | |
| regional-bus | |
| regional-coach | |
| regional-train | |
| Where “general” represents disruption information affecting two or more modes | |
| e.g. “regional-train,regional-coach” would return planned disruption information | |
| for V/Line rail and coach services | |
| required: true | |
| - $ref: "#/parameters/devid" | |
| - $ref: "#/parameters/signature" | |
| responses: | |
| 200: | |
| description: | | |
| schema: | |
| title: DisruptionsResponse | |
| type: object | |
| properties: | |
| general: | |
| $ref: "#/definitions/disruptions" | |
| metro-train: | |
| $ref: "#/definitions/disruptions" | |
| metro-tram: | |
| $ref: "#/definitions/disruptions" | |
| metro-bus: | |
| $ref: "#/definitions/disruptions" | |
| regional-train: | |
| $ref: "#/definitions/disruptions" | |
| regional-coach: | |
| $ref: "#/definitions/disruptions" | |
| regional-bus: | |
| $ref: "#/definitions/disruptions" | |
| example: | |
| metro-train: | |
| - title: "Buses replacing trains on the Cranbourne and Pakenham lines after 8.45pm: Saturday 15 February 2014" | |
| url: http://ptv.vic.gov.au/disruptions/buses-replacing-trains-on-thecranbourne-and-pakenham-lines-after-8-45pm-saturday-15-february-2014/ | |
| description: Due to signalling upgrades and construction work as part of the Springvale Level Crossing Removal, buses will replace all trains between Westall and Dandenong after 8.45pm on Saturday 15 February. | |
| publishedOn: 2014-01-29T23:30:54Z |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment