Wiki

Home

#!http
GET /bannerads

To access listed adverts send a GET request to https://www.ma3route.com/findit-api/v2/json/bannerads

Parameters

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

id a long value. The server returns a json object of the ad 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 ad id of the last ad the client saw/read. This is basically the offset for other api implementations.
town_id a long value. This is the id of the town you want updates for. lastread_id and limit are checked if provided.
context a string value. This is the context of the ads you would like to fetch. For targeted advertising, we set the context of each banner ad to be e.g traffic,reports e.t.c. Supported ad contexts can be fetched here https://www.ma3route.com/findit-api/v2/json/adcontext. town_id, lastread_id and limit are checked if provided.
size a string value. This is the size of the ads you would like to fetch. Supported sizes can be fetched here https://www.ma3route.com/findit-api/v2/json/adsizes. town_id, context, lastread_id and limit are checked if provided.

Server Response

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

data is a json object/array representing an ad or a list of ads respectively.

Sample Response

#!json

{
   "meta":{
      "listsize":1
   },
   "data":[
      {
         "id":2,
         "title":"Zusha",
         "isactive":true,
         "date":"Jun 27, 2015 2:58:20 AM",
         "datelong":1435363100,
         "url":"http://bit.ly/zusharoadsafety",
         "mediaurl":"http://www.ma3route.com/images-uploadapi/ma3route_banner_reports2.jpg",
         "town":{
            "id":1,
            "name":"Nairobi",
            "isActive":true,
            "description":"Nairobi is the capital of Kenya.",
            "country":"Kenya",
            "latitude":"-1.29207",
            "longitude":"36.82195"
         },
         "visitscount":1,
         "context":"reports",
         "size":"large"
      }
   ]
}

#!https
POST /bannerads

To post a banner ad send a POST request to https://www.ma3route.com/findit-api/v2/json/bannerads

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

#!json
{
    "title":"?",     
    "mediaurl":"?",
    "url":"?",
    "context":"?",
    "town":"?",
    "size":"?"
}

* title a string value. Mandatory. * town a string value. The town you want the ad to appear. Mandatory. Fetch supported towns from https://www.ma3route.com/findit-api/v2/json/towns * context a string value. The ad context. Mandatory. Fetch supported contexts from https://www.ma3route.com/findit-api/v2/json/adcontext * mediaurl a fully qualified url string for the ad banner. Banner can be 728x150(Large) or 300x300(Medium). Mandatory. * url a fully qualified url string for the ad redirect site. Mandatory. * email a string value. A valid email address for the user posting the ad. e.g info@ma3route.com. Mandatory. * size a string value. The ad size. Mandatory. Fetch supported sizes from https://www.ma3route.com/findit-api/v2/json/adsizes

Once you post, you will receive a response from the server, which is a JSON object that will indicate if you successfully posted the ad 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"
   }
}

OR

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