MercadoLibre is the biggest e-commerce site in Latin America (similar to eBay) and it has recently released a REST API to retrieve information from the published items, the users and most of the actions that can be performed in the site. The API returns its results encoded in JSON and has a public interface that is freely accessible and a private interface that can only be accessed by a MercadoLibre user using OAuth authentication in an application.
This implementation addresses the public and private sides of the API. There are two main modules:
mlapi: which provides uncached access to the API; and 2)mlapi_cache: which caches the results returned by the API. The cached entries are automatically removed once they expire.
You will need a fairly recent version of Erlang and rebar installed in your path. So far it has been tested with Erlang/OTP R14 and R15 on Ubuntu Linux 11.04, 11.10 and 12.04 but will most probably work on other platforms too.
Clone the mlapi repository and issue the following commands:
git clone https://github.com/jcomellas/mlapi.git
cd mlapi
make depends
make
That will download all the required Erlang dependencies and compile the project. After that you can start using the modules in it.
You can easily test the modules within the Erlang shell. To enter the shell with the required paths already set run:
make console
Once you're in the Erlang shell you need to start the mlapi application. You
can start it and its dependencies by doing:
mlapi:start().
Now we're ready to rock. Keep in mind the following type specifications:
-type error() :: {error, Reason :: atom() | {atom(), any()}}.
-type ejson_key() :: binary().
-type ejson_value() :: binary() | boolean() | integer() | float() | null.
-type ejson() :: {[{ejson_key(), ejson_value() | ejson()}]}.
-type proplist() :: [{Key :: atom(), Value :: term()}].
-type format() :: ejson | proplist | record | dict | orddict | raw.
-type option() :: {format, format()} | {record, RecordName :: atom()} | refresh.
-type response_element() :: ejson() | proplist() | tuple() | dict() | orddict:orddict() | binary().
-type response() :: response_element() | [response_element()] | error().
All of the available functions that retrieve information from MLAPI are very similar and follow a syntax like the following one:
-spec mlapi:user(mlapi_user_id(), [mlapi:option()]) -> mlapi:response().
This is also a short version like:
-spec mlapi:user(mlapi_user_id()) -> mlapi:response().
All the functions can receive options in the last argument. The most important one would be the one to specify the format of the result. It follows the syntax:
{format, Format :: mlapi:format()}
where Format can be one of:
| Format | Description |
| ejson | returns the JSON document as decoded by the ejson Erlang library (see https://github.com/benoitc/ejson) |
| proplist | returns the parsed JSON document as a property list (see http://www.erlang.org/doc/man/proplists.html) |
| record | returns the parsed JSON document as the corresponding record as defined in the mlapi.hrl header file |
| dict | returns the parsed JSON document as an dict (see http://www.erlang.org/doc/man/dict.html) |
| orddict | returns the parsed JSON document as an orddict (see http://www.erlang.org/doc/man/orddict.html) |
| raw | returns the unparsed binary with the JSON document |
For example, if we wanted to format the result as a proplist we'd do:
mlapi:sites([{format, proplist}]).
And we'd receive:
[[{id,<<"MLA">>},{name,<<"Argentina">>}],
[{id,<<"MLB">>},{name,<<"Brasil">>}],
[{id,<<"MCO">>},{name,<<"Colombia">>}],
[{id,<<"MCR">>},{name,<<"Costa Rica">>}],
[{id,<<"MEC">>},{name,<<"Ecuador">>}],
[{id,<<"MLC">>},{name,<<"Chile">>}],
[{id,<<"MLM">>},{name,<<"Mexico">>}],
[{id,<<"MLU">>},{name,<<"Uruguay">>}],
[{id,<<"MLV">>},{name,<<"Venezuela">>}],
[{id,<<"MPA">>},{name,<<"Panamá">>}],
[{id,<<"MPE">>},{name,<<"Perú">>}],
[{id,<<"MPT">>},{name,<<"Portugal">>}],
[{id,<<"MRD">>},{name,<<"Dominicana">>}]]
For the time being, you can retrieve the following information provided by MLAPI:
- Search by keywords, by category, by seller ID and by seller nickname
- Sales
- Orders
- Items
- Users
- Categories
- Domains
- Pictures
- Global and category trends
- Geolocation information
- Credit card issuers
- Payment types and methods
- Listing exposures, types and their prices
- Currencies and their conversion rates
- Cities, states and countries
- Sites
You can check the exported functions in src/mlapi.erl to see the complete interface.
There is a variant of the mlapi module called mlapi_cache that caches
the results it receives in Mnesia. The time-to-live of each type of result can
be specified in the mlapi_metatable Mnesia table (see src/mlapi_cache.erl
for its definition). The interface is the same as the one provided by the
mlapi module.
The resulting documents can be accessed very easily with the use of normal Erlang tools. In particular, I'd recommend Bob Ippolito's kvc for the proplist format and Anton Lavrik's erlson for the orddict format.