Home

#!https
GET /trafficupdates

To access traffic updates send a GET request to https://www.ma3route.com/findit-api/v2/json/trafficupdates

Parameters

Note: If no other parameter otherthan the default parameters is supplied, the server returns a list of updates for the last 7 days or 500 latest updates, whichever comes first.

• id a long value. The server returns a json object of the update whose id equals the value supplied.

• limit a long value. This is the maximum list size to be returned. The default limit is 500.

• countonly a boolean value, true/false. If true, the server will return the number of items in the requested list. Otherwise, the server will return the required list as a json array.

• lastread_id is a long value. This is the update id of the last update the client saw/read. This is basically the offset for other api implementations.

• email is a text value. If provided, the server returns a list of updates posted by the user whose email is provided. limit, countonly and lastread_id are also checked if they are provided.

• favorite a boolean value, true/false. If true, the server returns the list of updates favorited by the user whose email is provided. limit, countonly and lastread_id are also checked if they are provided.

• days has an integer value. Ma3Route API only gives a list of updates for the last one week or 500 updates, whichever comes first i.e any value greater than 7 will be disregarded. Any value less than 7 is valid. limit, countonly and lastread_id are also checked if they are provided.

• hours has an integer value. If this parameter is provided, the server returns a list of updates that were posted within the hours supplied as parameter value. The days parameter is disregarded in this case. limit, countonly and lastread_id are also checked if they are provided.

• minutes has an integer value. If this parameter is provided, the server returns a list of updates that were posted within the number of minutes supplied as parameter value. The days and hours parameters are disregarded in this case. limit, countonly and lastread_id are also checked if they are provided.

• town_id a long value. This is the id of the town you want updates for.

• csroadnames is a comma separated string. This is used for filtering updates. To get updates that contain the keyword "ngong road", you'll have the parameter csroadnames=ngong road. To get updates that contain the keyword "ngong road" and "mombasa road", add csroadnames=ngong road,mombasa road. Note that limit, countonly, lastread_id and town_id are also checked if they are provided.

• withinproximity a boolean value, true/false. If true, the server returns a list of updates within a user's proximity. latitude and longitude MUST be provided. days, hours, minutes and town_id are also checked if they are provided.

Server Response

The response is a JSON object with "meta" and "data" properties.

data is a json object/array representing an update or a list of updates respectively. Each object has the properties: id, * severity, description, reportedby, town, latitude, longitude, placefrom, placeto, date and datelong.

• id is the numeric unique identifier for each update.
• severity is the weight of each update: clear, moderate, bumper to bumper, impassable etc.
• description is the user description of the traffic situation.
• reportedby is the user string identifier. We recommend users to use their twitter handles e.g @okune.
• town is a JSON object that represents the town affected by the update. Each town object has id, name etc.
• latitude and longitude represent the fine location. We collect this from updates coming from smartphones in which users have enabled location sharing. Otherwise this fields are empty.
• placefrom and placeto are JSON objects that represent a route. These objects are empty if the user did not specify the specific route.
• date gives the time-stamp of the update. It is exposed in the format “MMM dd, yyyy hh:mm:ss aa”. Give this date object the timezone “GMT-07:00” before converting to the device timezone and display it in your preferred format. This converts the date from the server timezone to the device timezone.
• datelong gives the time as long in milliseconds.
• mediaurl gives the url to an image attached to an update.
• csmediaurls gives a comma separated list of urls of images attached to an update.
• profilepic_url gives the url of the image to display along side an update. This is resolved at the back-end. Use this if displaying a list of updates e.g on android app.
• favoritescount gives the number of times an update has been favorited on Ma3Route.
• viewscount gives the number of times an update's url has been opened.

Sample response

#!json
{
   "meta":{
      "listsize":500
   },
   "data":[
      {
         "id":264542,
         "town":{
            "id":1,
            "name":"Nairobi",
            "isActive":true,
            "description":"Nairobi is the capital of Kenya.",
            "country":"Kenya",
            "latitude":"-1.29207",
            "longitude":"36.82195"
         },
         "severity":"General Info",
         "date":"Jun 8, 2015 3:53:34 AM",
         "isactive":true,
         "description":"Is traffic Police department still in existence? Thought there were plans to disband it",
         "reportedby":"@Arcndege",
         "isapproved":true,
         "latitude":"",
         "longitude":"",
         "user":{
            "userId":1265,
            "email":"username@whatever.com",
            "firstname":"firstname",
            "alias":"@alias",
            "lastname":"lastname",
            "role":"Admin",
            "mobile":"Not Provided"
         },
         "sharelocation":false,
         "replyto":0,
         "datelong":1433760814991,
         "mediaurl":"",
         "favoritescount":0,
         "viewscount":1,
         "profilepic_url":"http://www.ma3route.com/images/ic_launcher.png"
      }
   ]
}

#!https
POST /trafficupdates

The request body should be a json object with it's fields as in:

#!json
{
    "town_id":"?",
    "placefrom_id":"?",
    "placeto_id":"?",
    "description":"?",
    "severity":"?",
    "reportedby":"?",
    "latitude":"?",
    "longitude":"?"
}

To delete

• delete boolean true/false. Deletes the update if the user is admin/owner. Update id and user email MUST be provided. Sign the request with user access token.

To favorite

• favorite boolean true/false. Favorites the update. Update id and user email MUST be provided. Sign the request with user access token.

To unfavorite

• unfavorite boolean true/false. Unfavorites the update. Update id and user email MUST be provided. Sign the request with user access token.

Once you post, you will receive a response from the server, which is a JSON object that will indicate if you successfully posted the update or if an error occurred. For now, we are not pointing to the exact cause of the error, this will be done in future enhancements.

Server response

#!json
{
   "meta":{      
   },
   "data":{
      "success":true,
      "message":"You successfully posted an update"
   }
}

#!json
{
   "meta":{      
   },
   "data":{
      "success":false,
      "message":"Error! Check that you have all mandatory properties in the object. Avoid empty strings!"
   }
}