NAV Navbar
javascript shell ruby python

Introduction

What are you going to build?

Welcome to the GoMetro API. You can use our API to access GoMetro API endpoints, where you can get information on various forms of public transport in our database. You will be able to draw out information like stop details, route descriptions, operating schedules, GoMetro line updates and a full multi-modal trip planner in our Version 1 API. More functionality will be supported with future releases of our API.

We have been collecting data and information on how South African cities move for the last 5 years. We are now opening up that data to other developers to build awesome solutions and hacks on our baseline datasets. We have up-to-date information on Metrorail operations across South Africa, bus systems like Golden Arrow, BRT systems like MyCiti and the entire minibus taxi network in Cape Town.

Currently our API has full support for Cape Town. We will be adding more cities very soon - including Johannesburg, Pretoria, Ekhurhuleni, Durban, Rustenburg, Mbombela, Umtata, Kampala, George, Port Elizabeth, East London, Bloemfontein, Polokwane and others.

We have example language bindings in javascript only, with Shell, Ruby, and Python coming soon. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Our API base url:

http://proserver.gometro.co.za/api/v1

Authentication





In future GoMetro will use API keys to allow access to the API. Stay informed by registering our website.

Metrorail

Currently only the Western Cape region is supported

Get rail routes

GET: "http://proserver.gometro.co.za/api/v1/rail/routes"



The above command returns JSON structured like this:

[
  {
    "id": "5:90000160",
    "longName": "CapeFlats",
    "mode": "RAIL",
    "color": "905846",
    "agencyName": "Metrorail Western Cape"
  },
  {
    "id": "5:90000164",
    "longName": "Malmesbury",
    "mode": "RAIL",
    "color": "00A651",
    "agencyName": "Metrorail Western Cape"
  },
  {
    "id": "5:90000163",
    "longName": "Central",
    "mode": "RAIL",
    "color": "00BAF2",
    "agencyName": "Metrorail Western Cape"
  },
  {
    "id": "5:90000175",
    "longName": "Southern",
    "mode": "RAIL",
    "color": "ED1C24",
    "agencyName": "Metrorail Western Cape"
  },
  {
    "id": "5:90000128",
    "longName": "Northen",
    "mode": "RAIL",
    "color": "3C763D",
    "agencyName": "Metrorail Western Cape"
  }
]

This endpoint retrieves all rail routes.

HTTP Request

GET <BASEURL>/rail/routes/

URL Parameters

There are no query parameters for this endpoint.

Get rail stops by route

GET: "http://proserver.gometro.co.za/api/v1/rail/routes/5:90000160/stops"



The above command returns JSON structured like this:

[
  {
    "id": "5:f12",
    "code": "f12",
    "name": "Athlone",
    "lat": -33.962688,
    "lon": 18.502
  },
  {
    "id": "5:f16",
    "code": "f16",
    "name": "Ottery",
    "lat": -34.013376,
    "lon": 18.495
  },
  {
    "id": "5:f15",
    "code": "f15",
    "name": "Wetton",
    "lat": -34.001818,
    "lon": 18.501
  },
  {
    "id": "5:f1",
    "code": "f1",
    "name": "Salt Rivier",
    "lat": -33.926709,
    "lon": 18.465
  }
]

This endpoint retrieves rail stops by route.

HTTP Request

GET <BASEURL>/rail/routes/<routeId>/stops

URL Parameters

Parameter Description
routeId The ID of the route to retrieve stops for

Get rail stop details

GET: "http://proserver.gometro.co.za/api/v1/rail/stop/5:f12"



The above command returns JSON structured like this:

{
  "id": "5:f12",
  "name": "Athlone",
  "lat": -33.962688,
  "lon": 18.502,
  "code": "f12",
  "zoneId": "2",
  "locationType": 0,
  "wheelchairBoarding": 0,
  "vehicleType": -999,
  "vehicleTypeSet": false
}

This endpoint retrieves info for a specific stop in our rail data.

HTTP Request

GET <BASEURL>/rail/stop/<stopId>

URL Parameters

Parameter Description
stopId The ID of the stop to retrieve data for

Get rail line updates

GET: "http://proserver.gometro.co.za/api/v1/rail/lineupdates"



The above command returns JSON structured like this:

{
  "routes_announcements": [
    {
      "event_id": "8733293",
      "create_date": "2017-03-03 06:23:54",
      "creator_id": "2191264",
      "type_id": "126",
      "message_id": "8733292",
      "receiver": "routes",
      "receiver_id": "90000160",
      "portal_id": "",
      "target_id": "90000160",
      "target2_id": "",
      "use_grouping": "0",
      "title": "Other Announcement",
      "message": "Trains cancelled due to sets out of service: Train no 0505 the 05:34 train from cape Town to Heathfield, Train no 0508 the 06:23 train from Heathfield to Cape Town, Train no 0513 the 06:21 train from Cape Town to Heathfield, Train no 0514 the 07:08 train from Heathfield to Cape Town, Train no 0519 the 07:10 train from Cape Town to Heathfield, Train no 0520 the 07:57 train from Heathfield to Cape Town.",
      "user_name": "Western Cape Metrorail"
    },
    {
      "event_id": "8733098",
      "create_date": "2017-03-03 05:41:01",
      "creator_id": "2191264",
      "type_id": "126",
      "message_id": "8733097",
      "receiver": "routes",
      "receiver_id": "90000160",
      "portal_id": "",
      "target_id": "90000160",
      "target2_id": "",
      "use_grouping": "0",
      "title": "Other Announcement",
      "message": "Trains cancelled due to sets out of service: Train no 0505 the 05:34 train from cape Town to Heathfield, Train no 0508 the 06:23 train from Heathfield to Cape Town, Train no 0513 the 06:21 train from Cape Town to Heathfield, Train no 0514 the 07:08 train from Heathfield to Cape Town, Train no 0519 the 07:10 train from Cape Town to Heathfield, Train no 0520 the 07:57 train from Heathfield to Cape Town.",
      "user_name": "Western Cape Metrorail"
    }
  ]
}

This endpoint retrieves lineupdates for Western Cape.

HTTP Request

GET <BASEURL>/rail/lineupdates/<stopId>

URL Parameters

Parameter Description
stopId The ID of the stop to retrieve data for

Cape Town Taxis

Get taxi routes

GET: "http://proserver.gometro.co.za/api/v1/taxi/routes"



The above command returns JSON structured like this:

[
  {
    "id": "2:8806774",
    "shortName": "CAPETX27",
    "longName": "BaysideToDunoon",
    "mode": "FERRY",
    "agencyName": "Cape Town Taxis"
  },
  {
    "id": "2:6943042",
    "shortName": "CAPETX142",
    "longName": "GugulethuToNyanga",
    "mode": "FERRY",
    "agencyName": "Cape Town Taxis"
  },
  {
    "id": "2:6853105",
    "shortName": "CAPETX371",
    "longName": "MitchellsPlainToMowbry",
    "mode": "FERRY",
    "agencyName": "Cape Town Taxis"
  }
 ]

This endpoint retrieves our Cape Town taxi routes.

HTTP Request

GET <BASEURL>/taxi/routes/

URL Parameters

There are no query parameters for this endpoint.

Get taxi stops by route

GET: "http://proserver.gometro.co.za/api/v1/taxi/routes/2:8806774/stops"



The above command returns JSON structured like this:

[
  {
    "id": "2:8806781",
    "code": "8806774",
    "name": "Taxi Stop300",
    "lat": -33.83123,
    "lon": 18.51384
  },
  {
    "id": "2:8806785",
    "code": "8806774",
    "name": "Taxi Stop298",
    "lat": -33.83306,
    "lon": 18.526136
  },
  {
    "id": "2:8806775",
    "code": "8806774",
    "name": "Taxi Stop303",
    "lat": -33.82508,
    "lon": 18.49072
  },
  {
    "id": "2:8806783",
    "code": "8806774",
    "name": "Taxi Stop299",
    "lat": -33.831665,
    "lon": 18.515657
  },
  {
    "id": "2:8806779",
    "code": "8806774",
    "name": "Taxi Stop301",
    "lat": -33.829384,
    "lon": 18.507118
  },
  {
    "id": "2:8806777",
    "code": "8806774",
    "name": "Taxi Stop302",
    "lat": -33.826954,
    "lon": 18.497896
  }
]

This endpoint retrieves our Cape Town taxi stops by route.

HTTP Request

GET <BASEURL>/taxi/routes/<routeId>/stops

URL Parameters

Parameter Description
routeId The ID of the route to retrieve stops for

Get taxi stop details

GET: "http://proserver.gometro.co.za/api/v1/taxi/stop/2:8806781"



The above command returns JSON structured like this:

{
  "id": "2:8806781",
  "name": "Taxi Stop300",
  "lat": -33.83123,
  "lon": 18.51384,
  "code": "8806774",
  "desc": "Cape town road300",
  "locationType": 0,
  "wheelchairBoarding": 0,
  "vehicleType": -999,
  "vehicleTypeSet": false
}

This endpoint retrieves info for a specific stop in our Cape Town taxi data.

HTTP Request

GET <BASEURL>/taxi/stop/<stopId>

URL Parameters

Parameter Description
stopId The ID of the stop to retrieve data for

MyCiti

Get MyCiti routes

GET: "http://proserver.gometro.co.za/api/v1/myciti/routes"



The above command returns JSON structured like this:

[
  {
    "id": "13:1101",
    "shortName": "D01",
    "longName": "Khayelitsha East - Civic Centre",
    "mode": "TRAM",
    "color": "f0648b",
    "agencyName": "MyCiti"
  },
  {
    "id": "13:1103",
    "shortName": "D03",
    "longName": "Mitchells Plain East - Civic Centre",
    "mode": "TRAM",
    "color": "74c599",
    "agencyName": "MyCiti"
  },
  {
    "id": "13:2001",
    "shortName": "A01",
    "longName": "Airport - Civic Centre",
    "mode": "TRAM",
    "color": "899AA5",
    "agencyName": "MyCiti"
  }
]

This endpoint retrieves MyCiti routes.

HTTP Request

GET <BASEURL>/myciti/routes/

URL Parameters

There are no query parameters for this endpoint.

Get MyCiti stops by route

GET: "http://proserver.gometro.co.za/api/v1/myciti/routes/13:1101/stops"



The above command returns JSON structured like this:

[
  {
    "id": "13:348",
    "name": "Lindela",
    "lat": -34.056993,
    "lon": 18.69717033
  },
  {
    "id": "13:29",
    "name": "Civic Centre",
    "lat": -33.92082723,
    "lon": 18.42985692
  },
  {
    "id": "13:347",
    "name": "Kuyasa",
    "lat": -34.0553875,
    "lon": 18.691905
  },
  {
    "id": "13:355",
    "name": "Vuyani",
    "lat": -34.03724,
    "lon": 18.68092267
  }
]

This endpoint retrieves our Cape Town taxi stops by route.

HTTP Request

GET <BASEURL>/myciti/routes/<routeId>/stops

URL Parameters

Parameter Description
routeId The ID of the route to retrieve stops for

Get MyCiti stop details

GET: "http://proserver.gometro.co.za/api/v1/myciti/stop/13:348"



The above command returns JSON structured like this:

{
  "id": "13:348",
  "name": "Lindela",
  "lat": -34.056993,
  "lon": 18.69717033,
  "locationType": 0,
  "wheelchairBoarding": 0,
  "vehicleType": -999,
  "vehicleTypeSet": false
}

This endpoint retrieves info for a specific MyCiti stop.

HTTP Request

GET <BASEURL>/myciti/stop/<stopId>

URL Parameters

Parameter Description
stopId The ID of the stop to retrieve data for

Golden Arrow Bus

Get Golden Arrow bus routes

GET: "http://proserver.gometro.co.za/api/v1/ga/routes"



The above command returns JSON structured like this:

[
  {
    "id": "6:2311",
    "shortName": "147_A",
    "longName": "MFULENILWANDLEMALIBU",
    "mode": "BUS",
    "agencyName": "Golden Arrow"
  },
  {
    "id": "6:2795",
    "shortName": "091_F",
    "longName": "WESPOORTKILLARNEY GARDENSNEW EISLEBEN",
    "mode": "BUS",
    "agencyName": "Golden Arrow"
  },
  {
    "id": "6:2310",
    "shortName": "146_B",
    "longName": "PRESTIGE COLLEGEBELLVILLEMIKE PIENAAR",
    "mode": "BUS",
    "agencyName": "Golden Arrow"
  },
  {
    "id": "6:2794",
    "shortName": "091_E",
    "longName": "KAPTEINSKLIPKILLARNEY GARDENSMERRYDALE",
    "mode": "BUS",
    "agencyName": "Golden Arrow"
  }
 ]

This endpoint retrieves Golden Arrow bus routes.

HTTP Request

GET <BASEURL>/ga/routes/

URL Parameters

There are no query parameters for this endpoint.

Get Golden Arrow bus stops by route

GET: "http://proserver.gometro.co.za/api/v1/ga/routes/6:2311/stops"



The above command returns JSON structured like this:

[
  {
    "id": "6:S5132",
    "code": "42",
    "name": "BUS 5132",
    "lat": -33.999829,
    "lon": 18.725962
  },
  {
    "id": "6:S5056",
    "code": "4508",
    "name": "BUS 5056",
    "lat": -33.996338,
    "lon": 18.701745
  },
  {
    "id": "6:S5111",
    "code": "1985",
    "name": "BUS 5111",
    "lat": -33.988815,
    "lon": 18.718762
  },
  {
    "id": "6:S5672",
    "code": "3789",
    "name": "BUS 5672",
    "lat": -34.120379,
    "lon": 18.865693
  }
 ]

This endpoint retrieves Golden Arrow bus stops by route.

HTTP Request

GET <BASEURL>/ga/routes/<routeId>/stops

URL Parameters

Parameter Description
routeId The ID of the route to retrieve stops for

Get Golden Arrow bus stop details

GET: "http://proserver.gometro.co.za/api/v1/ga/stop/6:S5132"



The above command returns JSON structured like this:

{
  "id": "6:S5132",
  "name": "BUS 5132",
  "lat": -33.999829,
  "lon": 18.725962,
  "code": "42",
  "desc": "Bus Stop5132",
  "locationType": 0,
  "wheelchairBoarding": 0,
  "vehicleType": -999,
  "vehicleTypeSet": false
}

This endpoint retrieves info for a specific Golden Arrow bus stop.

HTTP Request

GET <BASEURL>/ga/stop/<stopId>

URL Parameters

Parameter Description
stopId The ID of the stop to retrieve data for

Accessibility Score

Quantify all public transport available within 800m of a single point including Minibus Taxi Routes.

For any point in Cities that we support, GoMetro is able to provide a complete inventory of public transport routes and stops within 800m of a given point. This includes train, BRT, bus and minibus taxi routes that are continuously collected and updated by commuters themselves. Our Access Score is a benchmark of transport availability and can be used to compare different points around the world as to transport availability.

Our Accessibility Score currently is only supported in Cape Town. Other cities to follow shortly.

Get accessibility

GET "http://proserver.gometro.co.za/api/v1/accessibility/-33.903490/18.420468/150/"
Ruby examples coming soon
Python examples coming soon
Shell examples coming soon

The above command returns JSON structured like this:

{
  "stops": [
    {
      "id": "13:19",
      "name": "Breakwater",
      "lat": -33.9030545,
      "lon": 18.4192915,
      "dist": 118,
      "modes": "BRT",
      "routeCount": 2
    }
  ],
  "stopCount": 1,
  "routeCount": 2,
  "longestRoutes": [
    {
      "id": "13:104",
      "shortName": "104",
      "longName": "Sea Point - Waterfront - Civic Centre",
      "mode": "BRT",
      "color": "FFDD00",
      "agencyName": "MyCiti",
      "routerId": "South_Africa",
      "distance": 10.23
    },
    {
      "id": "13:P104",
      "shortName": "104",
      "longName": "Sea Point - Waterfront - Civic Centre",
      "mode": "BRT",
      "color": "FFDD00",
      "agencyName": "MyCiti",
      "routerId": "South_Africa",
      "distance": 9.97
    }
  ],
  "routesDistance": 20.2,
  "accessibilityScore": 0
}

This endpoint retrieves the accessibility score for an area

HTTP Request

GET <BASEURL>/accessibility/<lat>/<lng>/<rad>/

Query Parameters

Parameter Description
lat Latitude
lng Longitude
rad Radius

Multimodal Routing

The GoMetro Routing API responds to journey planning requests with itineraries in a JSON or XML representation. Plan multi-modal walking, wheelchair, bicycle and transit trips. Take travel time, road type, safety, and elevation into account, and allow users to customize the weighting of these three factors:

Imports data from GTFS, OpenStreetMap, and digital elevation models – we are a completely open data warehouse and can connect any data type to any other data type in the transport operating environment. Supports one-to-many and many-to-many searches for planning, alternatives analysis, and accessibility research purposes. Typically provides multiple itineraries in a fraction of a second even in large metropolitan networks – our response times are very efficient.

Get multimodal routing

GET "http://proserver.gometro.co.za/api/v1/trips/Artscape%20Theatre%20Centre/10%20church%20street,%20durbanville/2017-03-03/10:00/RAIL,BUS,FERRY,TRAM,GONDOLA,WALK"
Ruby examples coming soon
Python examples coming soon
Shell examples coming soon

The above command returns JSON structured like this:

{
  "date": 1488528000000,
  "from": {
    "name": "BUS 807",
    "lon": 18.430152,
    "lat": -33.920658,
    "orig": "",
    "vertexType": "NORMAL"
  },
  "to": {
    "name": "BUS 3943",
    "lon": 18.648731,
    "lat": -33.834074,
    "orig": "",
    "vertexType": "NORMAL"
  },
  "itineraries": [
    {
      "duration": 3558,
      "startTime": 1488528190000,
      "endTime": 1488531748000,
      "walkTime": 0,
      "transitTime": 3304,
      "waitingTime": 254,
      "walkDistance": 0,
      "walkLimitExceeded": false,
      "elevationLost": 0,
      "elevationGained": 0,
      "transfers": 1,
      "legs": [
        {
          "startTime": 1488528190000,
          "endTime": 1488531467000,
          "departureDelay": 0,
          "arrivalDelay": 0,
          "realTime": false,
          "distance": 25190.738939604,
          "pathway": false,
          "mode": "BUS",
          "route": "015_A",
          "agencyName": "Golden Arrow",
          "agencyUrl": "http://www.cccta.org",
          "agencyTimeZoneOffset": 7200000,
          "routeType": 3,
          "routeId": "6:713",
          "interlineWithPreviousLeg": false,
          "tripShortName": "Golden Arrow Trips",
          "headsign": "Bus Stop54194",
          "agencyId": "6000",
          "tripId": "6:713",
          "serviceDate": "20170303",
          "from": {
            "name": "BUS 807",
            "stopId": "6:S807",
            "stopCode": "2435",
            "lon": 18.430152,
            "lat": -33.920658,
            "departure": 1488528190000,
            "orig": "",
            "stopIndex": 2,
            "stopSequence": 54184,
            "vertexType": "TRANSIT"
          },
          "to": {
            "name": "BUS 3938",
            "stopId": "6:S3938",
            "stopCode": "720",
            "lon": 18.647079,
            "lat": -33.832471,
            "arrival": 1488531467000,
            "departure": 1488531721000,
            "stopIndex": 13,
            "stopSequence": 54195,
            "vertexType": "TRANSIT"
          },
          "legGeometry": {
            "points": "pc`nE_snoB\\g@xH_JiS}RtHuOzB{KBye@n@yIA{Hy@wIi@{_@NaRoCmh@mPclAcEkNMgDfAmOsBkSmDiQ_IuUcGgLmF}HesC}`DkDwFmDcJeCwNe@{Nd@_KbAsHjCwJvS{f@`BuFhBqLb@wMa@mKke@kaFYuJRiHvAcKlCgIhR_d@vB_MZ{HqGkkC]cH_Fw[_C_HiIo@_HaAyj@}H_Cy@kBqAiFuDmZkEoJuAiIkAkRoCeY_KqHgBoKwAuw@mE_DcAgGaFaDgCgCaBsEuCgFgBSGiI_BKAmEUaAGkRfCwG|G",
            "length": 74
          },
          "routeShortName": "015_A",
          "routeLongName": "CITYDURBANVILLEN1 FREEWAY",
          "rentedBike": false,
          "transitLeg": true,
          "duration": 3277,
          "intermediateStops": [
            {
              "name": "BUS 3981",
              "stopId": "6:S3981",
              "stopCode": "4492",
              "lon": 18.634704,
              "lat": -33.883158,
              "arrival": 1488530755000,
              "departure": 1488530755000,
              "stopIndex": 3,
              "stopSequence": 54185,
              "vertexType": "TRANSIT"
            },
            {
              "name": "BUS 3921",
              "stopId": "6:S3921",
              "stopCode": "4493",
              "lon": 18.637036,
              "lat": -33.874942,
              "arrival": 1488530867000,
              "departure": 1488530867000,
              "stopIndex": 4,
              "stopSequence": 54186,
              "vertexType": "TRANSIT"
            },
            {
              "name": "BUS 3929",
              "stopId": "6:S3929",
              "stopCode": "192",
              "lon": 18.638968,
              "lat": -33.869408,
              "arrival": 1488530951000,
              "departure": 1488530951000,
              "stopIndex": 5,
              "stopSequence": 54187,
              "vertexType": "TRANSIT"
            },
            {
              "name": "BUS 3927",
              "stopId": "6:S3927",
              "stopCode": "209",
              "lon": 18.639688,
              "lat": -33.867614,
              "arrival": 1488530974000,
              "departure": 1488530974000,
              "stopIndex": 6,
              "stopSequence": 54188,
              "vertexType": "TRANSIT"
            },
            {
              "name": "BUS 3926",
              "stopId": "6:S3926",
              "stopCode": "2207",
              "lon": 18.639788,
              "lat": -33.865918,
              "arrival": 1488530999000,
              "departure": 1488530999000,
              "stopIndex": 7,
              "stopSequence": 54189,
              "vertexType": "TRANSIT"
            },
            {
              "name": "BUS 3950",
              "stopId": "6:S3950",
              "stopCode": "200",
              "lon": 18.645823,
              "lat": -33.843843,
              "arrival": 1488531299000,
              "departure": 1488531299000,
              "stopIndex": 8,
              "stopSequence": 54190,
              "vertexType": "TRANSIT"
            },
            {
              "name": "BUS 3953",
              "stopId": "6:S3953",
              "stopCode": "2205",
              "lon": 18.647169,
              "lat": -33.842452,
              "arrival": 1488531324000,
              "departure": 1488531324000,
              "stopIndex": 9,
              "stopSequence": 54191,
              "vertexType": "TRANSIT"
            },
            {
              "name": "BUS 3947",
              "stopId": "6:S3947",
              "stopCode": "2204",
              "lon": 18.648381,
              "lat": -33.840209,
              "arrival": 1488531356000,
              "departure": 1488531356000,
              "stopIndex": 10,
              "stopSequence": 54192,
              "vertexType": "TRANSIT"
            },
            {
              "name": "BUS 3946",
              "stopId": "6:S3946",
              "stopCode": "201",
              "lon": 18.648798,
              "lat": -33.838438,
              "arrival": 1488531382000,
              "departure": 1488531382000,
              "stopIndex": 11,
              "stopSequence": 54193,
              "vertexType": "TRANSIT"
            },
            {
              "name": "BUS 3945",
              "stopId": "6:S3945",
              "stopCode": "2203",
              "lon": 18.648904,
              "lat": -33.837362,
              "arrival": 1488531399000,
              "departure": 1488531399000,
              "stopIndex": 12,
              "stopSequence": 54194,
              "vertexType": "TRANSIT"
            }
          ],
          "steps": []
        }
}
}
}

Plan multi-modal walking, wheelchair, bicycle and transit trips.

HTTP Request

GET <BASEURL>/trips/<from>/<to>/<date>/<time>/<modes>

Query Parameters

Parameter Description
from Starting Point
to Destination
date The date
time The time
modes Mode options - RAIL,BUS,FERRY,TRAM,GONDOLA,WALK

Errors

The GoMetro API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API key is wrong
403 Forbidden – The data requested is hidden for administrators only
404 Not Found – The specified data could not be found
405 Method Not Allowed – You tried to access data with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The data requested has been removed from our servers
429 Too Many Requests – You’re requesting too much data! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.