Design considerations

JSON format

The 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.

JSONP Usage

The API will respond JSONP if you provide a callback parameter. The value of this parameter will be used as the callback function.
Example:

curl -X GET https://api.mercadolibre.com/currencies/ARS

Response:

{
  "id": "ARS",
  "description": "Peso argentino",
  "symbol": "$",
  "decimal_places": 2,
}

For a JSONP response, add a callback parameter as follows:

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

Response:

foo
( [ 200, {
  "Content-Type": ["text/javascript;charset=UTF-8"],
  "Cache-Control": ["max-age=3600,stale-while-revalidate=1800, stale-if-error=7200"]
}, {
  "id": "ARS",
  "symbol": "$",
  "description": "Peso argentino",
  "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.

Handling errors

The standard format of an error is as follows:

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

Reducing 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. All other fields of the original response will be ignored.

curl -X GET https://api.mercadolibre.com/currencies?attributes=id
[
  {
  "id": "BRL"
  },
  {
  "id": "UYU"
  },
  {
  "id": "CLP"
  },
  ...
]

Using OPTIONS

The API will deliver documentation in JSON format using OPTIONS.

curl -X OPTIONS https://api.mercadolibre.com/currencies
{
  "name":"Monedas",
    "description":"Devuelve información correspondiente al ISO de las monedas que se usan en MercadoLibre.",
  "attributes": {
     "id":"ID de la moneda (Código ISO)",
        "description":"Denominación oficial de la moneda",
      "symbol":"Símbolo ISO para representar la moneda",
        "decimal_places":"Número de decimales manejados con la moneda"
  },
  "methods": [
     {
            "method":"GET",
            "example":"/currencies/",
            "description":"Devuelve el listado con todas las monedas."
      },
      {
            "method":"GET",
            "example":"/currencies/:id",
          "description":"Devuelve información con respecto a una moneda específica."
      }
  ],
  "related_resources":[],
  "connections": {
        "id":"/currencies/:id"
  }
}

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.

curl https://api.mercadolibre.com/sites/MLA/search?q=ipod nano

En la sección de paginación de la respuesta JSON, puedes ver la cantidad total de artículos que coinciden con la búsqueda y el valor de offset con el limit por defecto aplicado.

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

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 https://api.mercadolibre.com/sites/MLA/search?q=ipod nano&limit=3

This action retrieves a JSON data with a set of 3 articles, as illustrated below:

{
  "site_id": "MLA",
  "query": "ipod nano",
  "paging": {
  "total": 284,
  "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 articles that follow the default response:

curl https://api.mercadolibre.com/sites/MLA/search?q=ipod nano&offset=50
{
  "site_id": "MLA",
  "query": "ipod nano",
  "paging": {
  "total": 285,
  "offset": 50,
  "limit": 50,
  },
  "results": [...],
  "sort": {...},
  "available_sorts": [...],
  "filters": [...],
  "available_filters": [...],
}

This response retrieves 50 articles 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 https://api.mercadolibre.com/sites/MLA/search?q=ipod nano&offset=3&limit=3

This action retrieves a JSON data with a set of 5 articles, as below:

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