There are some things you should know about our API to make your life easier.

Table of Contents

All responses are JSON encoded.

JSON is a lightweight text-based open standard designed for human-readable data interchange. You can read more here.

Our API supports and returns JSON by default.

We also return HTML responses when you surfing the API through a browser.

We use the Accept header to decide which response we return.

To overcome same origin policy, JSONP is also supported.

The same origin policy is an important security concept. To overcome it, we suggest using JSONP and CORS.

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.

For example, doing:

$ curl https://api.mercadolibre.com/currencies/ARS

will return:

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

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

$ curl https://api.mercadolibre.com/currencies/ARS?callback=foo

which will respond:

foo(
    [
        200, 
        {
            "ETag":"2995de5a04da39af0a8677b1d02d1cdb",
            "Vary":"Accept,Accept-Encoding",
            "Content-Type":"application/json;charset=UTF-8",
            "Cache-Control":"max-age=86400"
        }, 
        {
            "id":"ARS",
            "description":"Peso argentino",
            "symbol":"$",
            "decimal_places":2
        }
    ]
);

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

  • Http status code
  • Http 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.

CORS

Cross-origin resource sharing (CORS) is a web browser technology specification which defines ways for a web server to allow its resources to be accessed by a web page from a different domain. This is a way to overcome the same origin policy.

All the APIs return a special header:

Access-Control-Allow-Origin: *

This allows the browser to access information provided by the API, even if it is from a different domain.

All the major browsers have support for CORS.

So basically this means that you don’t have to do anything and you get to access the API directly from your browser doing regular ajax calls with all the standard methods and avoiding things like JSONP.

All requests/responses are UTF-8 encoded.

User: Are you really telling me that I can only use UTF-8 with MELI APIs?
Us: Yes.
User: Really?
Us: Yes.
User: Only?
Us: Yes. We hope this has been enlightening for you.
User: But, I must--
Us: Thank you, come again.
User: But--
Us: Thank you, come again.

Any similarities with a dialog between Apu, Kiwk-E Mart’s CEO, and Homer are no coincidence.

All dates are ISO 8601 encoded.

We use ISO 8601 to encode dates in responses.

Not all dates will use the same timezone. So dates will include the proper timezone.

All errors have a standard format.

The standard format of an error is as follows:

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

Use selection to reduce the amount of returned attributes.

In order to have smaller responses, with less data, you can add the attributes parameter with a comma separating the list of fields that should be included in the response. All the other fields of the original response will be ignored.

This is supported only for array responses.

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

This is supported only for array responses.

Filter by the IDs of resources

If you have a list of IDs of the resources you want to retrieve, you can avoid doing N calls to get them by just doing 1 call. This is done by adding the ids parameter to the query string.

$ curl https://api.mercadolibre.com/currencies?ids=ARS,USD

API will provide documentation in JSON format using OPTIONS.

There is a standard format to get API documentation. Use the OPTIONS http method to get a JSON encoded response that will describe the API with all the allowed methods and connections between another part of the API.

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

Please, rate this article