Chapter 2: Adverts Management

We have seen in first chapter how to setup the application, in this chapter we will see how to manage adverts.

Retrieve Adverts

URL to call:


By default you will get a 20 adverts, when you call this url.

The _format can be json or xml. By default it is set to json.

You can make filters to retrieve adverts list. So to filter result, just add some parameters. in the next section, a description of available parameters.


Parameter Requirements Is nullable Description Default
categoryGroup Integer YES The catgory group to filter on
category Integer YES The catgory to filter on. it will be ignored if categoryGroup was set.
advertType Integer YES restrict results on this advertType 1
city Integer YES restrict results to this city
town Integer YES restrict results to this town
search string YES The text to search
page Integer YES Page of the overview. 1
limit Integer YES Adverts count limit. For future use 20
sort (a.price|a.modifiedAt)+ YES Sort parameter. a.modifiedAt
direction (asc|desc)+ YES Sort direction desc

Example of use

  • Get Vehicles in Tunis city sorted by date of update in descendant order
  • Get apartments for vacation rentals in  Nasr I Town


The response,by default is Json. You can use any JSON client to parse it.

The response looks like this:

  "page": 1,
  "limit": 20,
  "pages": 58,
  "total": 1159,
  "_links": {
    "self": {
      "href": "/api/v1/adverts?sort=a.modifiedAt&direction=desc&advertType=1&page=1&limit=20"
    "first": {
      "href": "/api/v1/adverts?sort=a.modifiedAt&direction=desc&advertType=1&page=1&limit=20"
    "last": {
      "href": "/api/v1/adverts?sort=a.modifiedAt&direction=desc&advertType=1&page=58&limit=20"
    "next": {
      "href": "/api/v1/adverts?sort=a.modifiedAt&direction=desc&advertType=1&page=2&limit=20"
  "_embedded": {
    "adverts": [
        "id": 2276,
        "categoryGroup": {
          "id": 3,
          "name": "Vêtements et objets personnels",
          "_links": {
            "list": {
              "href": "/api/v1/adverts?categoryGroup=3"
        "photo": "uploads/adverts/ce11f8d29451f02b5d836cd43ca4f3a5bde65162.jpg",
        "description": "Montre AUGUST Steiner presque neuf  modèle 2014\r\nPrix:100dt",
        "title": "Montre AUGUST steiner",
        "price": 100,
        "city": {
          "id": 13,
          "name": "Manouba",
          "_links": {
            "list": {
              "href": "/api/v1/adverts?city=13"
        "modified_at": "2015-06-03T11:54:40+0100",
        "_links": {
          "self": {
            "href": "/api/v1/adverts/2276"


As result, you have two informations:

  • Metadata

page: what page you are browsing

limit: the limit of the rsults

pages: The total number of pages found that matches your query

The special _links:

It shows you the links of the paginator. Using this links, you can browse results without building a new query for the same criterias.

    • self: The URL of current page result
    • first: The URL of the first page  result
    • last: The URL of The last pasge
    • next: The URL of the next page.
  • Data

Data in “adverts” collection under  “_embedded” section.  It’s a normal Json content, so you can parse it using any Json Client.

There is a special key under “_links” of categoryGroup and city keys which is “list“.

"_links": {
            "list": {
              "href": "/api/v1/adverts?city=13"

It shows you that you can get all adverts in that categoryGroup using that URL (e.g: )

Response codes:

Code Description
200 OK
401 Unauthorized. If no apikey was given
403 Forbidden. Given apikey not exists or it was disbled
500 Server Error

Questions ?

If you have any question, please post it in the dedicated Forum Secion.

Previous: Chapter 1: Introduction & setup


Chapter 1: Introduction & setup

Our API uses HTTP verbs and a RESTful endpoint structure. WSSE is used as the API Authorization protocol. Request and response payloads are formatted as JSON.


A complete REST operation is formed by combining an HTTP method (or “verb”) with the full URI to the resource you’re addressing. For example, here is the operation to get the advert with ID 20:


Table of contents

  1. Create your professional account
  2. API Key Authentication

1. Create your professional account

To be able to use our API, you need to get a professional account. If you are not already registred in our plateform, you can register now. Now go to your member space and get your API KEY.

Ecran Mes applications
My applications screen

Create a new application

Suppose that you need to create an android application that can communicate with our plateform (publish adverts, retrieve adverts,…)

Once you have loggend with your professional account, go to “Mes applications“, then create a new one. Simply, you will be asked for the name of your application.

New application
New Application


Now you should wait to activate your application by AFARIAT. You will recieve an email when it’s done.

2. API KEY Authentication

Here we suppose that you have already an application enabled.

Now you have your API KEY that will allows you to communicate with our plateform. For each request you make, you should add this key. There are 2 ways to do that:

Add the API KEY as a query parameter:


Add the key in the request header
Content-Type application/json
The apikey requirements:

It should have exactly 64 caracters.


Chapter 2: Read Access Level

Get Started

About Afariat Tayara Platform

Afariat Tayara is more than a simple website where users pubish their adverts. Here you will learn how to communicate with our platform.


With our REST API, you can

  • Retrieve adverts
  • Pubish adverts
  • Manage your adverts

Access Levels


To facilitate communication with our plateform, we have developed two types of access.

1. READ Mode

Client can only read data. So, it can retrieves adverts, making search and viewing adverts. Here, you need to get only the API KEY. read more…

2. Manage Level

In addition of the READ Mode level, you will need to authenticate user that wants to create and manage his adverts. read more…