Choose operation and property type

Categories are a hierarchical set of groups in which items of a similar nature are listed, called “Category Tree”. Categories help users to easily browse the kind of items they want.
Each site has its own set of categories, which means that Argentina will have a unique set of categories, different from the ones you’ll find on Brazil, since each country has their own classified market particularities.
Before listing an item, you need to go through the category structure and choose the one in which you want to list. To help you make it, you can download the complete category hierarchy with ID and human-friendly names from our API.
To list a real estate property, you will have to choose the category_id according to operation and property type.

For second level categories, or information related to specific categories, you have to use the Categories resource sending the category Id as a URL parameter.Let’s see what we find under “Inmuebles” category:

You get the “path_from_root” and children_categories attributes. Use these attributes to browse through the category tree and find the specific category for your item.
As you can see, categories are based on property types first followed by operation type. You need to choose the children category.Example:

On this case the children_categories are “Venta” and “Alquiler”. You can list your real estate property under the one that suits you better.

Categories JSON

Making a call to a particular category will let you know the attributes that belong to it. Following you’ll find a description of some of these attributes.When you make a GET to the category_id, you’ll find all available attributes and you can know if they’re required to list under the category or if they’re optional.Example:

Name

This attribute shows a human-friendly label. Only by reading the Json above you now that, for example, this is a classified category that doesn’t allow to include shipping options, there are 1332 items listed under it, and you can include the price on ARS or USD.

Mandatory attributes

Mandatory attributes are set as “required” under the category detail. On the example above you can see that price and stock are required, coverage areas are not allowed and seller_contact is optional. Also specific category attributes like attributes like “Antigüedad” and “Estado” that has the tag “required”: true, need to be sent with the possible values detailed on the Json.

Category Dump

The category tree does not change very often. If you prefer, you can request a dump of the whole category tree for a given country site for offline processing. This API returns the category tree in JSON format within a gzip-encoded response.To get the categories for Brazil, use this URL:

~$ curl https://api.mercadolibre.com/sites/MLB/categories/all

To get the categories for Argentina, use this URL:

~$ curl https://api.mercadolibre.com/sites/MLA/categories/all

This URL contains 2 headers that can be used to check when the last dump was generated.

Choose category for your property

Choosing the right category for your real estate property will determine how quickly buyers will find your item and will improve your chances of selling it. For this reason, we highly recommend to use our Category predictor tool before listing an item.

Search by category

The search operation returns items which belong to a MercadoLibre item category, there can be tons of items under certains categories but don’t worry, you can paginate results, read about paging search results.To get every item under a given category, do as it follows:

The search response has a lot of parameters. Use 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.

Paging & sizing results

This tutorial will come handy for you from now on because it will help you to work with specific set of results each time you make an API call. Most resources have common url parameters to paginate and size results, which are: Limit and Offset.

Default values

Default values are offset=0 and limit=50.

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

In the paging section of the JSON response, you can see the total number of items that match the search and the offset value with the default limit applied.

.....
"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 retrieving just the first 3 items:

Define a range of results

It is possible to combine both parameters. You can retrieve items from the third to the sixth item in the original search result:
curl https://api.mercadolibre.com/sites/MLA/search?q=ipod nano&offset=3&limit=3This action retrieves a JSON data with an array of 5 items as shown: