Design considerations

JSON format

Is an open standard based on lightweight text designed for the exchange of readable data. You can read these types of messages through a browser, specific tools (Ex: Postman) or from any development that consumes the Mercado Libre API. For a JSONP response, add a callback parameter as follows:

Example:

curl -X GET https://api.mercadolibre.com/currencies/MXN?callback=foo

Response:

foo([
    200,
    {
        "Cache-Control": [
            "max-age=3600,stale-while-revalidate=1800, stale-if-error=7200"
        ],
        "Content-Type": [
            "text/javascript;charset=UTF-8"
        ]
    },
    {
        "id": "MXN",
        "symbol": "$",
        "description": "Peso Mexicano",
        "decimal_places": 2
    }
]);

As you can see, the response is an array with 3 values:

• HTTPS status code
• HTTPS response headers
• Body of the response

All JSONP responses will always be 200 OK. This is in order to give you the chance to handle 30x, 40x, and 50x responses on the client side. The real response data is in the array.

Error format

The standard format of an error is as follows:

{
  "message": "human readable text",
  "error": "machine_readable_error_code",
  "status": 400,
  "cause": [ ]
}

Reduce responses

To have shorter answers, with less data, you can add the attributes parameter with a comma by separating the list of fields that should be included in the response.

curl -X GET https://api.mercadolibre.com/currencies?attributes=id

Response:

[
    {
        "id": "ARS"
    },
    {
        "id": "BOB"
    },
    {
        "id": "BRL"
    },
    {
        "id": "CLF"
    },
    {
        "id": "CLP"
    },
    {
        "id": "COP"
    },
    {
        "id": "CRC"
    },
    {
        "id": "CUC"
    },
    {
        "id": "CUP"
    },
    {
        "id": "DOP"
    },
    {
        "id": "EUR"
    },
    {
        "id": "GTQ"
    },
    {
        "id": "HNL"
    },
    {
        "id": "MXN"
    },
    {
        "id": "NIO"
    },
    {
        "id": "PAB"
    },
    {
        "id": "PEN"
    },
    {
        "id": "PYG"
    },
    {
        "id": "USD"
    },
    {
        "id": "UYU"
    },
    {
        "id": "VEF"
    },
    {
        "id": "VES"
    }
]

Results pagination

You can define the page size of the result list. There are 2 parameters: limit and offset. Both parameters define the size block of the results. This article is based on the search example, but you can use pagination on each resource that is presented in the "pagination" response information, as shown below:

"paging": {
  "total": 285,
  "offset": 0,
  "limit": 50
}

Default values

The default values are offset=0 and limit=50 for most search and listing endpoints. In the pagination section of the JSON response, you can see the total number of items matching the search and the offset value with the default limit applied.

curl -X GET https://api.mercadolibre.com/sites/MLM/search?q=iphone

Response:

{
  "site_id": "MLM",
  "query": "iphone",
  "paging": {
    "total": 285,
    "offset": 0,
    "limit": 50
  },
  "results": [...],
  "sort": {...},
  "available_sorts": [...],
  "filters": [...],
  "available_filters": [...]
}

Limit

To reduce the page size, you can change the limit parameter. For example, if you are interested in recovering only the first 3 items:

curl -X GET https://api.mercadolibre.com/sites/MLM/search?q=iphone&limit=3

Response:

{
  "site_id": "MLM",
  "query": "iphone",
  "paging": {
    "total": 285,
    "offset": 0,
    "limit": 3
  },
  "results": [
    {...},
    {...},
    {...}
  ],
  "sort": {...},
  "available_sorts": [...],
  "filters": [...],
  "available_filters": [...]
}

Offset

By using the offset attribute, you can move the lower limit of the result block. For example, if you are interested in recovering the 50 items that follow the default response:

curl -X GET https://api.mercadolibre.com/sites/MLM/search?q=iphone&offset=50

Response:

{
  "site_id": "MLM",
  "query": "iphone",
  "paging": {
    "total": 285,
    "offset": 50,
    "limit": 50
  },
  "results": [...],
  "sort": {...},
  "available_sorts": [...],
  "filters": [...],
  "available_filters": [...]
}

This response retrieves 50 items starting from the first fifty.

Define a range of results

It is possible to combine both parameters. You can retrieve items from the third to the sixth in the original search result:

curl -X GET https://api.mercadolibre.com/sites/MLM/search?q=iphone&offset=3&limit=3

Response:

{
  "site_id": "MLM",
  "query": "iphone",
  "paging": {
    "total": 285,
    "offset": 3,
    "limit": 3
  },
  "results": [
    {...},
    {...},
    {...}
  ],
  "sort": {...},
  "available_sorts": [...],
  "filters": [...],
  "available_filters": [...]
}

Next: Best practices for listing items.