Home

#!https
GET /drivingreports

To access driving reports send a GET request to https://www.ma3route.com/findit-api/v2/json/drivingreports.

Parameters

Note: If no other parameter other than the default parameters is supplied, the server returns a list of 500 latest reports.

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

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

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

• country a string value. If provided, the server returns the list of reports for the country provided. limit and lastread_id are also checked if they are provided.

• regno a string value. If provided, the server returns the list of reports whose registration number is provided. limit and lastread_id are also checked if they are provided.

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

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

• withinproximity a boolean value, true/false. If true, the server returns a list of ads within a user's proximity. latitude and longitude MUST be 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,regno,drivetype, description, reportedby, country, latitude, longitude, date and datelong etc.

• id is the numeric unique identifier for each update.
• regno is the registration number of the the reported vehicle.
• drivetype is the weight of each report: careless, dangerous, involved in crime etc.
• description is the user description of the driving 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.
• 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":1
   }   "data":[
      {
         "id":5299,
         "isactive":true,
         "description":"@WilliamsRuto I spoted this lorry offload charcoal to a dealer in Mararui. http://t.co/gd0x83RROD",
         "regno":"GKB 649F",
         "drivetype":"Careless",
         "reportedby":"@Jablekid",
         "country":"Kenya",
         "date":"Jun 7, 2015 11:53:08 PM",
         "latitude":"-1.26876",
         "longitude":"36.80862",
         "user":{
            "userId":964,
            "email":"username@whatever.com",
            "firstname":"firstname",
            "lastname":"lastname",
            "role":"Admin",
            "mobile":"Not Provided"
         },
         "datelong":1433746388629,
         "mediaurl":"http://pbs.twimg.com/media/CG9ZApWVIAAkw5R.jpg",
         "favoritescount":0,
         "mediaurlbranded":"http://pbs.twimg.com/media/CG9ZRP7UkAAtEhj.png",
         "descriptionbranded":"@WilliamsRuto I spoted this lorry offload charcoal to a dealer in Mararui. pic.twitter.com/Ax4Wfvfhga",
         "profilepic_url":"http://www.ma3route.com/images/ic_launcher.png",
         "viewscount":30
      }
   ]
}

#!https
POST /drivingreports

Request body:

#!json
{
    "regno":"?",
    "description":"?",
    "drivetype":"?",
    "reportedby":"?",
    "latitude":"?",
    "longitude":"?",
    "country":"?"
}

To delete

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

To favorite

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

To unfavorite

• unfavorite boolean true/false. Unfavorites the report. Report 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!"
   }
}