Wiki

Home

#!http
GET /ads

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

Parameters

Note: If no 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.
type a string value. This is the type of the ads you would like to fecth. Supported adtypes can be fetched here http://www.ma3route.com/findit-api/v2/json/adtypes. lastread_id and limit are checked if provided.
targettext a string value. This is the text, e.g a traffic update. The server looks up ads that might be of value to the user who posted, e.g if the traffic update is about an accident, the server returns ambulance, towing etc ads. If the update is about a certain road, the server returns ads on that road. type, lastread_id and limit are checked if 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. 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":36,
         "title":"SMEP Microfinance Bank",
         "description":"SMEP, is a Christian based Microfinance Bank that seeks to empower the community and ensure we all realise our full potential and fulfill our dreams. We offer smart simple day to day financial solutions and products tailor made to suit your needs. Call us today or visit any of our branches nationwide.",
         "shortdescription":"SMEP, is a Christian based Microfinance Bank that seeks t...",
         "site":"http://smep.co.ke/",
         "social":"@SmepMFB",
         "photourl":"http://www.ma3route.com/images/adverts/advert1425236978631.jpg",
         "country":"Kenya",
         "category":"Asset Finance",
         "isActive":true,
         "ispaidfor":true,
         "date":"Mar 1, 2015 12:09:38 PM",
         "viewscount":816,
         "callscount":7,
         "place":{
            "id":2503,
            "town":{
               "id":1,
               "name":"Nairobi",
               "isActive":true,
               "description":"Nairobi is the capital of Kenya.",
               "country":"Kenya",
               "latitude":"-1.29207",
               "longitude":"36.82195"
            },
            "name":"SMEP Head Office",
            "isActive":true,
            "isapproved":false,
            "description":"An office building housing SMEP Microfinance Bank head office.",
            "latitude":"-1.29071",
            "longitude":"36.78136",
            "location":"On Kirichwa Road, off Argwings Kodhek Road"
         },
         "email":"info@smep.co.ke",
         "phone":"+254711606900 +254726156016",
         "areadescription":"Kirichwa Road, Argwings Kodhek"
      }
   ]
}

#!https
POST /ads

Use the user accessToken to perform this operation.

To post an update send a POST request to https://www.ma3route.com/findit-api/v2/json/ads

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

#!json
{
    "title":"?",
    "description":"?",
    "site":"?",
    "social":"?",
    "ademail":"?",
    "areadescription":"?",
    "place":"?",
    "phone":"?",
    "mediaurl":"?",
    "category":"?",
    "days":"?"
}

* title a string value. Mandatory. * description a string value describing the ad. Mandatory. * site a fully qualified url string for the ad website. Mandatory. * phone a string value. The contact phone number for the ad. Mandatory. * place a string value. The main HQ location for the ad. Mandatory. Fetch supported places from http://www.ma3route.com/findit-api/v2/json/places * category a string value. The ad category. Mandatory. Fetch supported types from http://www.ma3route.com/findit-api/v2/json/adcategories * mediaurl a fully qualified url string for the ad logo. MUST be 110x110. Mandatory. * days an integer. Number of days the ad is supposed to run. Optional. * social a string value. Social media page id for the ad e.g @okune. Optional. * ademail a string value. A valid contact email address for the ad. e.g info@ma3route.com. Optional. * areadescription a comma separated string value. Gives other areas/roads where the business operates. Optional.

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!"
   }
}