Home

Ma3Route is a mobile/web/SMS platform that crowd-sources for transport data and provides users with updates on traffic, directions and driving reports.

The Ma3Route API enables you to perform CRUD(Create, Read, Update and Delete) operations on Ma3Route data from your application.

NOTE: For those developing nodejs apps, do not re-invent the wheel, use the ma3route node-sdk on github.

Start by registering your app to obtain API credentials. Be sure to use an account with a secure password to own these credentials. Note: For now, create an account at ma3route.com then email support[at]ma3route.com to have your apikey and secret. Do not forget to describe your project. We are opening this up to a few developers with exciting projects. Each app can only access specific datasets, so let us know which one(s) i.e, traffic feed, driving reports, matatu directions e.t.c.

Once you have the Consumer Key and Consumer Secret, you will be required to generate HMAC-SHA256 signature which will be passed as a parameter (“signature”) to Ma3Route API end points. HMAC allows your application to verify the password (or private key) without requiring you to embed it in the request, and also verifies the basic integrity of the request. We are going to breakdown this documentation into modules: traffic updates, driving reports, directions etc. The generic functionality e.g user registration and login will be covered separately and we will highlight the importance of each.

Before we get into details about each API end point, note that we have set some standards in our API which cut across the board:

Each request to the server must have a signature. This is HMAC-SHA256 encoded string. To generate your signature, hash the entire endpoint url; baseurl, query parameters (ordered alphabetically by key names) and body using your Ma3Route API secret. apikey and timestamp(long value) MUST be included in the query parameters before hashing.

For actions requiring user authentication, generate your signature by hashing the entire endpoint url; baseurl, post parameters(ordered alphabetically by key names) and body using the user's acesstoken. How to get the user accesstoken is covered under Login. apikey, timestamp(long value) and email MUST be included in the post parameters before hashing.

Signature generation algorithm (in pseudocode)

1. Initialize empty string signatureBase
2. Append percent-encoded request path (NOT the query string) to signatureBase
3. Append “?” character to signatureBase
4. Initialize empty string parameterString
5. For every key/value pair in query string
6. Append percent-encoded key to the parameterString
7. Append “=” character to parameterString
8. Append percent-encoded value to the parameterString
9. If there are more key/value pairs, append “&” character to the parameterString
10. Append percent-encoded parameterString to signatureBase
11. Append percent-encoded POST/PUT data jsonString to signatureBase
12. Sign the signatureBase string using HMAC/SHA256 algorithm and your secret key as a key which yields signatureBytes
13. Convert signatureBytes to hexString. The result is the request signature

Each GET server response is a json object which has meta and data properties.

meta is a json object that can contain any/all of the following properties if the return type i.e the value of data is a json array:

• listsize is the number of items in the returned list, that is if the data object returned is a json array.

• latestid is the the id of the latest item in the returned list.

• oldestid is the the id of the oldest item in the returned list.

• nextpageurl is a text value. This is the url for the api end point to fetch the next batch of updates if the initial request had lastread_id and/or limit.

• prevpageurl is a text value. This is the url for the api end point to fetch the previous list of updates if the initial request had lastread_id and/or limit.

meta is a json object that can contain any/all of the following properties if the return type i.e the value of data is a single json object:

• itemid is the the id of the item i.e. the returned object.

• itemurl is the the id of the item i.e. the returned object.

• viewscount is the the number of times the returned item has been viewed.

• favoritescount is the the number of times the returned item has been favorited.

The details for the data property will be given for each api endpoint.

Each POST server response is a json object which has success, message and object properties.

success is a boolean value, true/false. If true, the POST was successful, else there were errors during POSTing.

message is a text value. This is the detailed feedback from the server. If an error occured, it will be the description of the error.

object this returns the affected object as a json in the event the object fields were updated.