New API endpoints

[joshmcarthur]

The new Metlink website is also using a new API hostname - https://backend.metlink.org.nz. This API is similar to, but different from the old API serving the old Metlink site.

So far, the only endpoint I have found and consumed is for stop departures, e.g. https://backend.metlink.org.nz/api/v1/stopdepartures/4404

This returns similar data to the old API:

{
  "farezone": "2/3",
  "closed": false,
  "departures": [
    {
      "stop_id": "4404",
      "service_id": "25",
      "direction": "inbound",
      "operator": "TZM",
      "origin": {
        "stop_id": "4419",
        "name": "KhandallahVlg-A"
      },
      "destination": {
        "stop_id": "4947",
        "name": "Highbury"
      },
      "delay": "-PT48S",
      "vehicle_id": "3443",
      "name": "NgaioGorgeRd (105)",
      "arrival": {
        "aimed": "2021-02-12T16:09:00+13:00",
        "expected": "2021-02-12T16:08:12+13:00"
      },
      "departure": {
        "aimed": "2021-02-12T16:09:00+13:00",
        "expected": "2021-02-12T16:08:12+13:00"
      },
      "status": "ontime",
      "wheelchair_accessible": true
    },
    {
      "stop_id": "4404",
      "service_id": "26",
      "direction": "inbound",
      "operator": "TZM",
      "origin": {
        "stop_id": "4419",
        "name": "KhandallahVlg-A"
      },
      "destination": {
        "stop_id": "5520",
        "name": "Brandon St"
      },
      "delay": "PT1M14S",
      "vehicle_id": "3427",
      "name": "NgaioGorgeRd (105)",
      "arrival": {
        "aimed": "2021-02-12T16:23:00+13:00",
        "expected": "2021-02-12T16:24:14+13:00"
      },
      "departure": {
        "aimed": "2021-02-12T16:23:00+13:00",
        "expected": "2021-02-12T16:24:14+13:00"
      },
      "status": "ontime",
      "wheelchair_accessible": true
    },
    {
      "stop_id": "4404",
      "service_id": "25",
      "direction": "inbound",
      "operator": "TZM",
      "origin": {
        "stop_id": "4419",
        "name": "KhandallahVlg-A"
      },
      "destination": {
        "stop_id": "4947",
        "name": "Highbury"
      },
      "delay": "-PT51S",
      "vehicle_id": "3834",
      "name": "NgaioGorgeRd (105)",
      "arrival": {
        "aimed": "2021-02-12T16:29:00+13:00",
        "expected": "2021-02-12T16:28:09+13:00"
      },
      "departure": {
        "aimed": "2021-02-12T16:29:00+13:00",
        "expected": "2021-02-12T16:28:09+13:00"
      },
      "status": "ontime",
      "wheelchair_accessible": true
    },
    // ...
  ]
}

Also, timetamp lookups:

curl 'https://backend.metlink.org.nz/api/v1/timetable' --data-raw '{"service":"402","start":"2021-02-12","end":"2021-02-12"}' --compressed

{
  "start": "2021-02-12",
  "end": "2021-02-12",
  "inbound": {
    "title": "Grenada North - Tawa Schools",
    "trips": [
      {
        "id": "402__1__100__MNM__3311__3311_1",
        "stops": [
          {
            "arrive": "",
            "depart": "08:05",
            "can_board": true,
            "can_alight": false,
            "is_timing_point": true,
            "stop": "3901",
            "zone": "4",
            "sequence": 0
          },
          ...

Route map:

curl 'https://backend.metlink.org.nz/api/v1/routemap' --data-raw '{"service":"402"}' --compressed

(Returns lots of GeoJSON)

Journey Plan:

curl 'https://backend.metlink.org.nz/api/v1/journeyplan' \
  --data-raw '{"coordinates":{"from":{"name":"Lambton Square, 180 Lambton Qy, Wellington, Wellington 6011","lat":-41.28172,"lng":174.776163},"to":{"name":"Porirua Saturday Market, Porirua, Wellington 5022","lat":-41.135684,"lng":174.839598}},"stops":{},"travel_options":{"max_changes":2,"walking_speed":4,"max_walking":2000},"transport_modes":["Bus","Train","Ferry","Cable Car"],"date":"2021-02-12","time":"12:13","when":"LeaveAfter"}' \
  --compressed

{
  "from": "-41.28172,174.776163",
  "to": "-41.135684,174.839598",
  "journey_time": "2021-02-12T16:14:00+1300",
  "journeys": [
    {
      "fares": {
        "DefaultFareType": "Adult",
        "HasPartialFares": false,
        "FareCosts": {
          "Adult": {
            "Snapper": "5.21",
            "Cash": "7.00",
            "Monthly": "156.30"
          },
          "OffPeak": {
            "Snapper": "3.91",
            "Monthly": false
          },
          "Child": {
            "Snapper": "2.61",
            "Cash": "3.50",
            "Monthly": "78.30"
          },
          "School": {
            "Snapper": "2.61",
            "Monthly": "78.30"
          },
          "Tertiary": {
            "Snapper": "3.91",
            "Monthly": false
          ...

There are some other API endpoints that use an API key:

• https://api.opendata.metlink.org.nz/v1/gtfs-rt/servicealerts
• https://api.opendata.metlink.org.nz/v1/gtfs-rt/vehiclepositions
• https://api.opendata.metlink.org.nz/v1/gtfs-rt/tripupdates

These APIs are all using (I assume), the Metlink Open Data APIs (https://opendata.metlink.org.nz/getting-started). These APIs require an API key that is available after registration, but is rate limited.

[nzphoenix]

Please don't use the APIs on backend.metlink.org.nz, they are getting authorisation added to them very soon, so anything built against these will cease to function.

Use the Open Data APIs which provides full GTFS and GTFS-RT feeds. Stop Departures is getting added to the Open Data APIs in the next week or two. You can self sign-up at opendata.metlink.org.nz

[reedwade]

Cool! I'm very out of date.

I've added a pointer to that on the top of the top level readme.