Receive notifications

Some events occur on MercadoLibre’s side and notifications are the only way to become aware of them.
Receiving notifications enables you to have a real-time feed of the changes that occur on the different resources of our API.
For example, if you listed an item that was then paused, if someone asked a question, if they bought an item, or even if they paid it and/or requested shipment.
An efficient way with no need to continuously query our API!

Contents:

Subscribe to notifications

If you want to start receiving notifications you need to go to our application manager, where you first created your app, and edit the details and specify the topics you will listen to.
Note: If you haven’t created your App yet, go to the Creating your app section.

Topics

– Callback URL de Notificaciones: Configure the public URL of your domain where you want to receive notifications for the different topics. E.g.: “http://myshoes-app.com/callbacks”.

– Topics: Select among different topics to receive their notifications.
Explanatory note: Topics orders, created_orders and payments are not user for real state, vehicles and services.

Available Topics

  • items – To get notified of any changes on an item you have published.
  • orders – To get notified of any changes to any of our confirmed sales.
  • created_orders – To get notified of your recently created sales when they are entered through the mandatory Mercado Pago flow.
    You will only get product data and number of units, since the purchase has not been confirmed yet. You should not take any action until it changes to “paid.”
    This is only to reserve stock, because if the buyer pays but the item is out of stock, the payment is automatically returned and the sale is canceled.
  • Explanatory note: Once the order is paid, notifications are sent just like in “orders;” thus, we suggest choosing only one of the topics to avoid duplicated events.

  • questions – To get notified of all questions asked or answered.
  • payments – To get notified when a payment is created on an order, or when its status changes.
  • pictures – To get notified only of images which cannot be displayed due to errors.
  • Note: Meanwhile, an automatic e-mail grouping the faulty images will be sent to the seller.

Considerations

  • Messages will be sent out and retried for a period of 12 hours. After that period, if not accepted by the app, they will be discarded.
  • Since we will send a POST to your URL, your application must acknowledge the reception with an HTTP status code 200, otherwise the message will be considered undelivered and it will be retried.
  • Your application must send a response within 20 seconds, otherwise it will timeout and be considered undelivered and will retry.

What events trigger notifications?

items

  • Changes on any of the attributes.
  • Changes on the status: The listing has to be reviewed by an operator and the status is changed to “under_review” or it is paused and the status is changed to “paused”.

orders

  • Stock decrement: Somebody purchases one of your items and the stock is decremented. A new order is created.
  • Pago: The buyer adds a payment order.
  • Shipping: There is new shipping information associated with the order or the shipping status which changes to: pending, ready to print, in transit, delivered, not delivered.
  • Feedback: The buyer rates you as a seller or you send feedback to the buyer. A feed is received on the order.
  • Explanatory note: while “orders” is made up of blocks of other APIs, not every data is displayed, as not all of them are required. These separate blocks may have changes, which triggers events and subsequent notifications related to the order, though sometimes there is no evident change from the previous JSON.

created_orders

  • A created_orders notification will be received when an order entered through the mandatory Mercado Pago flow is created. This is only to reserve stock.
  • Once the order is “paid,” all notifications are the same as those in the “orders” topic. If both topics are selected, you will receive notifications from both of them.

questions

  • You receive a new question.
  • You answer a question.
  • You delete a question that you considered inappropriate.

payments

  • A payment is generated.
  • Payment status changes.

pictures

  • When an image failed to be displayed due to errors.



Explanatory Note: In case you receive duplicate notifications, bear in mind that there are internal events that are not visible to the integrator, but that trigger notifications.

Get the details

After receiving a notification of one topic, you’ll need to make a GET to the resource to get the details and then, if you stored the previous Json, compare both.

items

Notification response:

{
  "resource": "/items/MLB139876",
  "user_id": 1234,
  "topic": "items",
  "received": "2011-10-19T16:38:34.425Z",
  "sent" : "2011-10-19T16:40:34.425Z",
}

This information will help you make a GET to the items resource:

curl -X GET https://api.mercadolibre.com/items/{Item_id}?access_token=ACCESS_TOKEN


orders and created_orders

Notification response:

{
    "resource": "/orders/139876",
    "user_id": 1234,
    "topic": "orders",
    "received": "2011-10-19T16:38:34.425Z",
    "sent" : "2011-10-19T16:40:34.425Z",
}

This information will help you make a GET to the orders resource:

curl -X GET https://api.mercadolibre.com/orders/{Order_id}?access_token=ACCESS_TOKEN


questions

Notification response:

{
  "resource": "/questions/139876",
  "user_id": 1234,
  "topic": "questions",
  "received": "2011-10-19T16:38:34.425Z",
  "sent" : "2011-10-19T16:40:34.425Z",
}

This information will help you make a GET to the questions resource:

curl -X GET https://api.mercadolibre.com/questions/{Question_id}?access_token=ACCESS_TOKEN


payments

Notification response:

{
  "resource": "/collections/1780558484",
  "user_id": 149218964,
  "topic": "payments",
  "application_id": 2470,
  "attempts": 1,
  "sent": "2016 - 01 - 15 T18: 12: 31.313 Z ",
  "received": "2016 - 01 - 15 T18: 12: 31.299 Z "
}

This information will help you make a GET to the collections resource:

curl -X GET https://api.mercadolibre.com/collections/{Payment_id}?access_token=ACCESS_TOKEN


pictures

Notification response:

{
  "messages": [
    {
      "_id": "123aaa456bbb789ccc",
      "application_id": "1234",
      "user_id": "123456789",
      "resource": "/pictures/12345-MLA1234567-20160729"/errors,
      "topic": "pictures",
      "sent": "2016-07-24T11:00:00.836Z",
      "received": "2016-07-24T11:00:00.836Z",
      "attempts": "2",
      "created_at": "2016-07-24T11:00:00.836Z"
    }
  ]
}

This information will help you make a GET to the picture resource:

curl -X GET https://api.mercadolibre.com/pictures/{picture_id}/errors?access_token=ACCESS_TOKEN

You should identify why the image failed to be correctly processed. See “considerations and best practices working with pictures”.

Feed History API

We keep a track of your notifications history and you can get it anytime by calling our feeds resource.
Example:

curl -X GET https://api.mercadolibre.com/myfeeds?app_id={App_id}

Response:

{
  "messages": [
  {
    "_id": "123aaa456bbb789ccc",
    "application_id": "1234",
    "user_id": "123456789",
    "resource": "/orders/12345678",
    "topic": "orders",
    "sent": "2014-10-24T11:00:00.836Z",
    "received": "2014-10-24T11:00:00.836Z",
    "attempts": "2",
    "http_code": "400",
    "created_at": "2014-10-24T11:00:00.836Z"
  }
}
}



Next topic: Searches and advanced features.

Please rate this

Update your listings

Once you have active listings on our marketplace, you’ll probably need to update and modify those listings from time to time. Follow this guide to know how to achieve this actions.

Contents:

Considerations

Not every field can be updated and this will vary whether the item had sales or not, and also remember your item must be active in order to be modified. You can modify the values for:

  • Title
  • Price
  • Phone Number
  • Pictures
  • Description*

*It’s not possible modify, just add a post.


Also remember that:

  • Category can’t be modified via API.
  • Listing type can be modified only once.

Update your item

Let’s see a basic example of updating an item title and price. The only thing you need is the item_id of the listed product and of course, the seller’s access_token.

Example:

 curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d
{
  "title": "Your new title",
  "price": 1000
}
https://api.mercadolibre.com/items/ITEM_ID?access_token=YOUR_ACCESS_TOKEN



Nice, your item title and price has been updated and you should receive a code 200 OK response status to know everything went well.
Keep in mind that it can take some time until you see the item’s information refreshed.

Description

It’s very easy to update a description, and is something you can do whether the item has bids or not, but since there are some considerations you need to keep when adding or replacing descriptions, check our descriptions article to make sure you get it right.

Pictures

You can always add or replace item pictures, refer to our working with pictures tutorial to know the best way to get through it.

Listing types

When you want more exposition on your item you need to make a listing type upgrade.Know the details and considerations and learn how to achieve an upgrade on our Listing types and Upgrades tutorial.

Changing listing status

Any item listed on our marketplace can hold different status, check the following description of each one:

  • closed: Finalizes your publication. Once closed, it cannot be reactivated again, but you can relist it.
  • paused: Pauses your publication. Once paused, it will not be visible to other MercadoLibre’s users, but it will not be closed and it can be reactivated later on.
  • active: Reactivates a previously paused item.

If you need to make any changes on the item status, you need to send any of these values for the “status” field, note the value is case sensitive and must be sent in lowercase.

Follow the example to pause an active item:
Example:

curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d
{
  "status":"paused"
}
https://api.mercadolibre.com/items/ITEM_ID?access_token=YOUR_ACCESS_TOKEN


Excellent! Your item has been paused. Now you can try to activate it again by making the exact same call sending “active” instead of “paused” as the status value.

If your item is currently closed and your intention is to relist it, check our relist article to achieve it right away.
Please check out the listing life-cycle article to know more about item status.

Delete listing

Deleting a listing has no way back, so be careful when you call this action. Also note that there’s no need to delete closed items since they’ll be discarded automatically after some time.
If you still need to delete an item, for example items in status: payment_required that won’t respond to ‘closed’ status, do as it follows:
Example:

curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d
{
"status": "closed"
}

{
"deleted":"true"
}
https://api.mercadolibre.com/items/ITEM_ID?access_token=YOUR_ACCESS_TOKEN

That’s it! Your item should be removed.



Next topic: Manage contacts & visits.

Please rate this

Authentication and Authorization

Mercado Libre platform allows you to work with our API public and private resources, via HTTP calls using GET, PUT, POST, DELETE and OPTIONS.
Public resources, such as available sites and categories, can be anonymously accessed, while private resources and user-own actions, such as listing an item, giving feedback or viewing purchase/sale information, require application-based authorization.
This guide explains the meaning of authentication and the authorization flow to be followed to obtain an access_token (access key to private resources for each user granting authorization to the application – valid for 6 hours).
For example:
Without access_token (Public Resource)

https://api.mercadolibre.com/users/226384143/

{
  "id": 226384143,
  "nickname": "TETE9928972",
  "registration_date": "2016-08-25T11:36:00.000-04:00",
  "country_id": "AR",
  "address": {
    "state": "AR-C",
    "city": "Palermo"
  },
  "user_type": "normal",
  "tags": [
    "normal",
    "test_user",
    "user_info_verified"
  ],
  "logo": null,
  "points": 100,
  "site_id": "MLA",
  "permalink": "http://perfil.mercadolibre.com.ar/TETE9928972",
  "seller_reputation": {
    "level_id": null,
    "power_seller_status": null,
    "transactions": {
      "period": "historic",
      "total": 1,
      "completed": 1,
      "canceled": 0,
      "ratings": {
        "positive": 0,
        "negative": 0,
        "neutral": 1
      }
    }
  },
  "buyer_reputation": {
    "tags": [
    ]
  },
  "status": {
    "site_status": "active"
  }
}


With access_token (Private Resource)

 
 https://api.mercadolibre.com/users/226384143?access_token=$ACCESS_TOKEN

{
  "id": 226384143,
  "nickname": "TETE9928972",
  "registration_date": "2016-08-25T11:36:00.000-04:00",
  "first_name": "Test",
  "last_name": "Test",
  "country_id": "AR",
  "email": "test_user_38730994@testuser.com",
  "identification": {
    "type": "DNI",
    "number": "1111111"
  },
  "address": {
    "state": "AR-C",
    "city": "Palermo",
    "address": "Test Address 123",
    "zip_code": "1414"
  },
  "phone": {
    "area_code": "01",
    "number": "1111-1111",
    "extension": "",
    "verified": false
  },
  "alternative_phone": {
    "area_code": "",
    "number": "",
    "extension": ""
  },
  "user_type": "normal",
  "tags": [
    "normal",
    "test_user",
    "user_info_verified"
  ],
  "logo": null,
  "points": 100,
  "site_id": "MLA",
  "permalink": "http://perfil.mercadolibre.com.ar/TETE9928972",
  "shipping_modes": [
    "custom",
    "not_specified"
  ],
  "seller_experience": "ADVANCED",
  "bill_data": {
    "accept_credit_note": null
  },
  "seller_reputation": {
    "level_id": null,
    "power_seller_status": null,
    "transactions": {
      "period": "historic",
      "total": 1,
      "completed": 1,
      "canceled": 0,
      "ratings": {
        "positive": 0,
        "negative": 0,
        "neutral": 1
      }
    }
  },
  "buyer_reputation": {
    "canceled_transactions": 0,
    "transactions": {
      "period": "historic",
      "total": null,
      "completed": null,
      "canceled": {
        "total": null,
        "paid": null
      },
      "unrated": {
        "total": null,
        "paid": null
      },
      "not_yet_rated": {
        "total": null,
        "paid": null,
        "units": null
      }
    },
    "tags": [
    ]
  },
  "status": {
    "site_status": "active",
    "list": {
      "allow": true,
      "codes": [
      ],
      "immediate_payment": {
        "required": false,
        "reasons": [
        ]
      }
    },
    "buy": {
      "allow": true,
      "codes": [
      ],
      "immediate_payment": {
        "required": false,
        "reasons": [
        ]
      }
    },
    "sell": {
      "allow": true,
      "codes": [
      ],
      "immediate_payment": {
        "required": false,
        "reasons": [
        ]
      }
    },
    "billing": {
      "allow": true,
      "codes": [
      ]
    },
    "mercadopago_tc_accepted": true,
    "mercadopago_account_type": "personal",
    "mercadoenvios": "not_accepted",
    "immediate_payment": false,
    "confirmed_email": false,
    "user_type": "simple_registration",
    "required_action": ""
  },
  "credit": {
    "consumed": 101.1,
    "credit_level_id": "MLA1"
  }
}

Contents:

Authentication

Authentication is the act or process of determining or confirming whether someone or something is, in fact, who or what it is declared to be.
In the case of a person, authentication consists in verifying his/her identity based on one or several factors, ensuring the sender’s data are correct.

Some authentication methods are:

  • Biomedical methods, fingerprints or retinal scan, etc.
  • Smart cards that save a user´s certificate information.
  • Standard methods based on passwords.
  • For example, to log into Mercado Libre we authenticate ourselves by entering our user name and password.

login

Authorization

Authorization is the process whereby we allow someone or something to access private resources.
The authorization should define which resources and operations can be performed, since it is not the same to grant read-only than read and write access.

How do we obtain authorization? Via the OAuth 2.0 Protocol, which is one of the most widely used protocols in open platforms (Twitter, Facebook, etc.) and a secure method to work with private resources.

OAuth offers:

  • Confidentiality, the user will never have to disclose his/her key.
  • Integrity, private data can only be viewed by applications with permits to do so.
  • Availability, data will always be available, on a need basis.

This protocol offers 4 possible operating modes, called Grant Types:

– The Authorization Code Grant Type (Server Side)
– The Implicit Grant Type (Client Side)
– The Password Credentials Grant Type
– The Client Credentials Grant Type

Although each of them is used for different purposes depending on the service being developed, below you will find the explanation of the first two types since they will allow you to work with our resources and develop tools for every user in Mercado Libre.

Client-side

The Client-side authorization flow is better suited for applications executing the client-side code, e.g., applications developed in javascript/ajax, Angular or mobile applications.
For more information about this flow, go to the tutorial “Client-Side Authorization

Server-side

The Server Side authorization flow is better suited for applications executing the server-side code, such as, applications developed in Java, Grails, Go, etc.
Note: This option will be helpful for applications executing cron jobs, to update product stock or operate when the user is not directly interacting with the application.
For more information about this flow, go to the tutorial “Server-Side Authorization

Get your access_token!

Enter the application ID you have just created:

*Please enter a valid Application ID
User informationJSON Response

-

Use our SDKs

Using our SDKs the authentication process will be simpler since our SDKs save you from coding the whole OAuth protocol from scratch.
Our community is already using them!
We already provide SDKs for:

If you find an enhancement or have a suggestion, you can share it with the community creating a Pull Request within our GitHub repository.

Considerations

Token validity and expiration
When you get an access_token, it will be immediately valid and usable to make requests to the API for a limited period of 6 hours.
There are also events which may cause an access_token to become invalid before the expiration time. For example: user changing his/her password, an application refreshing its App Secret and, of course, a user revoking permissions to your application.

Error Codes Reference

Error Description Possible solution
invalid_client

invalid client_id or client_secret

Invalid client_id and/or client_secret provided. Check your application info and verify parameters client_id and client_secret
invalid_grant

To create an access token the user {0} must have an active session, or your application should request authorization for offline_access scope.

The provided authorization grant is invalid, expired, revoked, or does not match the redirection URI used in the authorization request. Verify the parameter redirect_uri is the same configured in your application (App Manager), if this not solve, do a new request to obtain a new code.
invalid_grant

Error validating grant. Your authorization code or refresh token may have expired or it has already been used.

It has expired or it has already been used. Make a new request to obtain one new code or refresh_token.
invalid_grant

The client_id does not match the original.

Client ID does not match. The parameter client_id wasn’t found, to get your client_id, consult your application (App Manager).
invalid_grant

The redirect_uri does not match the original.

Redirect URI does not match the original. The parameter redirect_uri is not the same configured in you application, to get your a redirect_uri, consult your application (App Manager)
invalid_scope The requested scope is invalid, unknown, or malformed. The values allowed for parameter scope are:“offline_access”,”write”,”read”.
invalid_request

Wrong number of parameters with duplicate values.

The request is missing a required parameter, includes an unsupported parameter or parameter value, or is otherwise malformed. Verify that the parameters sent are valid and are not duplicated.
unsupported_grant_type

Unsupported grant type: ${0}.

The authorization grant type is not supported by the authorization server. The values allowed for parameter grant_type are“authorization_code” or “refresh_token”.
forbidden

The caller is not authorized to access this resource

The caller is not authorized to access. It is using the token of another user.



Next topic: Manage users



Related articles:

Server side authentication flow

Client side authentication flow

Please rate this

Searches & advanced features

If you want sellers to use the application that you developed to enhance their business, take into account that you have available a lot of useful market information to help sellers create sales strategies and make smart decisions timely. You can also develop a system to compare prices and attributes between different types of listings.

Follow our guides to learn how to take advantage of every resource!

Advanced queries

Help your sellers stay one step ahead in their business at all times. First, bear in mind that you will not be able to access private data from users who have not granted permission to your application. However, you can get public data about these users, such as who lists under the same categories as you, number of listings posted, prices and attributes included in their listings, categories under which they list, and number of contacts and visits they get on a daily basis.

Compare prices and attributes

You could suggest sellers using your system what’s the best price to sell their products and be competitive by analyzing the price of the same kind of products listed on MercadoLibre. To do this it may come handy to learn how to search items by category, then check the price field of those items and calculate the average.

You could also make a system that analyzes the classified market items prices and attributes so buyers can compare, localize, and find exactly what they’re looking for.

Follow the guides below to learn how to use the resources that will help you accomplish this:

Please rate this

Manage contacts & visits

Introduction

When users browse classified items, they are able to contact the item’s owner through a form displayed on the listing or they can see the owner’s phone.
There’s a difference between how it works with logged users and guest users. When guest users make a question on your item, the contact goes directly to your email inbox and it’s gonna be displayed on our contacts resource since it doesn’t follow the regular questions flow. When a user that has an account on our site and it’s logged in make a question, it follows the regular questions flow and you can use the Questions API.

To learn how to work with logged users questions, please follow our Manage questions and answers guide. Otherwise, keep reading.

Classified contacts guide

This guide will help you to collect data about questions and phone views on your classified items. Is a read only API, very useful to take metrics of your classified items. You can query data about questions, and keep a record of how many times the ‘See phone’ option was clicked on. You can query by user, item, dates and time windows.

Contents:

  • Parameters description
  • Total questions
  • Questions dated
  • Contact phone totals
  • Contact phone dated

Parameters description

Type Parameter Description
Integer {userId} User id.
Integer {itemId} Item id.
Date {dateFrom} Date, ISO format, that defines the start of the query.
Date {dateTo} Date, ISO format, that defines the end of the query.
Integer {limit} Optional. Max amount of items to return.
Integer {offset} Optional. Pagination.
Integer {last} Optional. Denotes how many hours/days back the sample will cover.
String {unit} Query unit, possible values: [ “day” , “hour”].
Date {ending} Optional. Date, ISO format, which states the time of completion of the sample, by default it’s the current date and time.
String {order} Optional. It’s sorts the results by date: [“desc”, “asc”] (by default it’s “asc”).

Total questions

You can get the total questions an specific item had, or the total questions a seller had in all of his items between a date range.

By item

curl -X GET https://api.mercadolibre.com/items/{Item_id}/contacts/questions?date_from={Date_from}&date_to={Date_to}

By user

curl -X GET https://api.mercadolibre.com/users/{User_id}/contacts/questions?date_from={Date_from}&date_to={Date_to}

Example:

curl -X GET https://api.mercadolibre.com/items/MLV421672596/contacts/questions?date_from=2014-08-01T00:00:00.000-03:00&date_to=2014-08-02T23:59:59.999

Response:

{
    "date_from": "2014-08-01T00:00:00.000-03:00",
    "date_to": "2014-08-02T23:59:59.999",
    "item_id": "MLV421672596",
    "total": 9
}

Questions dated

This resource let you get the questions on an specific item or by seller for a certain time window. Besides, you get details about contacts made on guest mode (unlogged or unregistered users) in between time intervals, by hour or by day.

By item

curl -X GET https://api.mercadolibre.com/items/{Item_id}/contacts/questions/time_window?last={Last}&unit={Unit}

If you need to concatenate items, do the following:

curl -X GET https://api.mercadolibre.com/items/{Item_id}/contacts/questions/time_window?ids={id1,id2}&last={Last}&unit={Unit}&ending={Ending_date}

By user

curl -X GET https://api.mercadolibre.com/users/{User_id}/contacts/questions/time_window?last={Last}&unit={Unit}

Example:

curl -X GET https://api.mercadolibre.com/items/MLA510272257/contacts/questions/time_window?last=2&unit=hour

Response:

{
    "item_id": "MLA510272257",
    "total": 0,
    "date_from": "2014-08-06T12:00:00Z",
    "date_to": "2014-08-06T14:00:00Z",
    "last": 2,
    "unit": "hour",
    "results": [
        {
            "date": "2014-08-06T12:00:00Z",
            "total": 0
        },
        {
            "date": "2014-08-06T13:00:00Z",
            "total": 0
        }
    ]
}

Contacts phone totals

You can get the total times the ‘See phone’ option was clicked on an item or for every item of an user between date ranges.

By item

curl -X GET https://api.mercadolibre.com/items/{Item_id}/contacts/phone_views?date_from={Date_from}&date_to={Date_to}

By user

curl -X GET https://api.mercadolibre.com/users/{User_id}/contacts/phone_views?date_from={Date_from}&date_to={Date_to}

Example:

curl -X GET https://api.mercadolibre.com/users/52366166/contacts/phone_views?date_from=2014-05-28T00:00:00.000-03:00&date_to=2014-05-29T23:59:59.999

Response:

{
    "date_from": "2014-05-28T00:00:00.000-03:00",
    "date_to": "2014-05-29T23:59:59.999",
    "total": 71,
    "user_id": "52366166"
}

Contacts phone dated

You can get the total times the ‘See phone’ option was clicked on an item or for every item of an user for a certain time window. Besides providing the total visits, the information is detailed and grouped by time intervals.

By item

curl -X GET https://api.mercadolibre.com/items/{Item_id}/contacts/phone_views/time_window?last={Last}&unit={Unit}

If you need to concatenate items:

curl -X GET https://api.mercadolibre.com/items/contacts/phone_views/time_window?ids={Id1,Id2}&last={Last}&unit={Unit}&ending={Ending_date}

By user

curl -X GET https://api.mercadolibre.com/users/{User_id}/contacts/phone_views/time_window?last={Last}&unit={Unit}

Example:

curl -X GET https://api.mercadolibre.com/items/contacts/phone_views/time_window?ids=MLA510272257,MLA489747739&last=2&unit=hour&ending=2014-05-28T00:00:00.000-03:00

Response:

[
    {
        "item_id": "MLA510272257",
        "total": 0,
        "date_from": "2014-05-28T02:00:00Z",
        "date_to": "2014-05-28T04:00:00Z",
        "last": 2,
        "unit": "hour",
        "results": [
            {
                "date": "2014-05-28T02:00:00Z",
                "total": 0
            },
            {
                "date": "2014-05-28T03:00:00Z",
                "total": 0
            }
        ]
    },
    {
        "item_id": "MLA489747739",
        "total": 0,
        "date_from": "2014-05-28T02:00:00Z",
        "date_to": "2014-05-28T04:00:00Z",
        "last": 2,
        "unit": "hour",
        "results": [
            {
                "date": "2014-05-28T02:00:00Z",
                "total": 0
            },
            {
                "date": "2014-05-28T03:00:00Z",
                "total": 0
            }
        ]
    }
]



Next topic: Subscribe to our feeds.

Please rate this

List properties

This guide will help you to list your first classified item on MercadoLibre using our API

Contents:

    Basics

    Real estate and classified items in general are the only kind of listing that allows users to display their contact information to the public, so when users are browsing properties to rent or buy and they have an interest on one of the properties you own, they can get in contact with you right away. So, basically, there aren’t any kind of transactions made on classified items, so you won’t sale or rent your property directly from our site, but you’ll expose it to every user that’s browsing the web for properties.

    Listing results

    Each item you list will appear in the listing results of a given search. For example, when a user search for the query “Casa en Mar del Plata”, as a result he will get a list of all items related. Your property can be on this list.
    When someone clicks on an item, the Item details page is displayed showing all the information about the item that was provided at the time of listing, keep reading to know more about it.

    Item details page

    This is the page on the frontend of our Marketplace for each item.
    When a user chooses an item from the result, this page displays the following item details:

    • Item_id
    • Title
    • City
    • Pictures
    • Price
    • Contact information
    • Contact form
    • Attributes
    • Detailed description

    Real estate item fields

    Let’s see a regular real estate item by API. This is easy since you only need to know the item_id associated to that item, and since it’s public you can get it from the item’s page. In Argentina, you will find it at the top of the page. You just need to add the site_id before the number you see and that’s it. Now you can call the Items resource to get all the information you need:

    Call:

    curl - X GET https://api.mercadolibre.com/items/{Item_id}

    Example:

    curl - X GET https://api.mercadolibre.com/items/MLA603335359

    Response:

    {
      "id": "MLA603335359",
      "site_id": "MLA",
      "title": "Semana.santa 190 Por Capacidad Deptos Complejo Angel Del Sol",
      "subtitle": null,
      "seller_id": 50152177,
      "category_id": "MLA50283",
      "official_store_id": null,
      "price": 190,
      "base_price": 190,
      "original_price": null,
      "currency_id": "ARS",
      "initial_quantity": 1,
      "available_quantity": 1,
      "sold_quantity": 0,
      "buying_mode": "classified",
      "listing_type_id": "gold_premium",
      "start_time": "2016-01-31T14:16:20.000Z",
      "stop_time": "2017-01-30T14:16:20.000Z",
      "condition": "used",
      "permalink": "http://inmueble.mercadolibre.com.ar/MLA-603335359-semanasanta-190-por-capacidad-deptos-complejo-angel-del-sol-_JM",
      "thumbnail": "http://mla-s1-p.mlstatic.com/23423-MLA20248368790_022015-I.jpg",
      "secure_thumbnail": "https://a248.e.akamai.net/mla-s1-p.mlstatic.com/23423-MLA20248368790_022015-I.jpg",
      "pictures": [
        {
          "id": "23423-MLA20248368790_022015",
          "url": "http://mla-s1-p.mlstatic.com/23423-MLA20248368790_022015-O.jpg",
          "secure_url": "https://a248.e.akamai.net/mla-s1-p.mlstatic.com/23423-MLA20248368790_022015-O.jpg",
          "size": "500x375",
          "max_size": "1200x900",
          "quality": ""
        },
        {
          "id": "23447-MLA20248368829_022015",
          "url": "http://mla-s2-p.mlstatic.com/23447-MLA20248368829_022015-O.jpg",
          "secure_url": "https://a248.e.akamai.net/mla-s2-p.mlstatic.com/23447-MLA20248368829_022015-O.jpg",
          "size": "500x375",
          "max_size": "1200x900",
          "quality": ""
        },
        {
          "id": "23431-MLA20248368726_022015",
          "url": "http://mla-s2-p.mlstatic.com/23431-MLA20248368726_022015-O.jpg",
          "secure_url": "https://a248.e.akamai.net/mla-s2-p.mlstatic.com/23431-MLA20248368726_022015-O.jpg",
          "size": "500x375",
          "max_size": "1200x900",
          "quality": ""
        },
        {
          "id": "23451-MLA20248368762_022015",
          "url": "http://mla-s2-p.mlstatic.com/23451-MLA20248368762_022015-O.jpg",
          "secure_url": "https://a248.e.akamai.net/mla-s2-p.mlstatic.com/23451-MLA20248368762_022015-O.jpg",
          "size": "500x375",
          "max_size": "1200x900",
          "quality": ""
        },
        {
          "id": "23446-MLA20248368859_022015",
          "url": "http://mla-s1-p.mlstatic.com/23446-MLA20248368859_022015-O.jpg",
          "secure_url": "https://a248.e.akamai.net/mla-s1-p.mlstatic.com/23446-MLA20248368859_022015-O.jpg",
          "size": "500x375",
          "max_size": "1200x900",
          "quality": ""
        },
        {
          "id": "23449-MLA20248368490_022015",
          "url": "http://mla-s2-p.mlstatic.com/23449-MLA20248368490_022015-O.jpg",
          "secure_url": "https://a248.e.akamai.net/mla-s2-p.mlstatic.com/23449-MLA20248368490_022015-O.jpg",
          "size": "500x375",
          "max_size": "1200x900",
          "quality": ""
        },
        {
          "id": "23466-MLA20248368893_022015",
          "url": "http://mla-s1-p.mlstatic.com/23466-MLA20248368893_022015-O.jpg",
          "secure_url": "https://a248.e.akamai.net/mla-s1-p.mlstatic.com/23466-MLA20248368893_022015-O.jpg",
          "size": "500x375",
          "max_size": "1200x900",
          "quality": ""
        },
        {
          "id": "23475-MLA20248368922_022015",
          "url": "http://mla-s2-p.mlstatic.com/23475-MLA20248368922_022015-O.jpg",
          "secure_url": "https://a248.e.akamai.net/mla-s2-p.mlstatic.com/23475-MLA20248368922_022015-O.jpg",
          "size": "500x375",
          "max_size": "1200x900",
          "quality": ""
        },
        {
          "id": "23425-MLA20248370717_022015",
          "url": "http://mla-s1-p.mlstatic.com/23425-MLA20248370717_022015-O.jpg",
          "secure_url": "https://a248.e.akamai.net/mla-s1-p.mlstatic.com/23425-MLA20248370717_022015-O.jpg",
          "size": "500x375",
          "max_size": "1200x900",
          "quality": ""
        },
        {
          "id": "23448-MLA20248370762_022015",
          "url": "http://mla-s1-p.mlstatic.com/23448-MLA20248370762_022015-O.jpg",
          "secure_url": "https://a248.e.akamai.net/mla-s1-p.mlstatic.com/23448-MLA20248370762_022015-O.jpg",
          "size": "500x375",
          "max_size": "1200x900",
          "quality": ""
        },
        {
          "id": "23403-MLA20248370781_022015",
          "url": "http://mla-s2-p.mlstatic.com/23403-MLA20248370781_022015-O.jpg",
          "secure_url": "https://a248.e.akamai.net/mla-s2-p.mlstatic.com/23403-MLA20248370781_022015-O.jpg",
          "size": "500x375",
          "max_size": "1200x900",
          "quality": ""
        },
        {
          "id": "23480-MLA20248371283_022015",
          "url": "http://mla-s2-p.mlstatic.com/23480-MLA20248371283_022015-O.jpg",
          "secure_url": "https://a248.e.akamai.net/mla-s2-p.mlstatic.com/23480-MLA20248371283_022015-O.jpg",
          "size": "500x375",
          "max_size": "1200x900",
          "quality": ""
        }
      ],
      "video_id": null,
      "descriptions": [
        {
          "id": "MLA603335359-1022043551"
        }
      ],
      "accepts_mercadopago": false,
      "non_mercado_pago_payment_methods": [
      ],
      "shipping": {
        "mode": "not_specified",
        "local_pick_up": false,
        "free_shipping": false,
        "methods": [
        ],
        "dimensions": null,
        "tags": [
        ]
      },
      "international_delivery_mode": "none",
      "seller_address": {
        "id": 153363213,
        "comment": "ferreteria antartida",
        "address_line": "av3 y paseo127 111111",
        "zip_code": "7165",
        "city": {
          "id": "TUxBQ1ZJTGU4OGM3",
          "name": "Villa Gesell"
        },
        "state": {
          "id": "AR-B",
          "name": "Buenos Aires"
        },
        "country": {
          "id": "AR",
          "name": "Argentina"
        },
        "latitude": -37.25747514,
        "longitude": -56.97445905,
        "search_location": {
          "neighborhood": {
            "id": "",
            "name": ""
          },
          "city": {
            "id": "TUxBQ1ZJTGU4OGM3",
            "name": "Villa Gesell"
          },
          "state": {
            "id": "TUxBUENPU2ExMmFkMw",
            "name": "Bs.As. Costa Atlántica"
          }
        }
      },
      "seller_contact": {
        "contact": "",
        "other_info": "",
        "area_code": "",
        "phone": "",
        "area_code2": "",
        "phone2": "",
        "email": "",
        "webpage": ""
      },
      "location": {
        "address_line": "PASEO 141 BIS Y 4 4100",
        "zip_code": "",
        "neighborhood": {
          "id": "",
          "name": ""
        },
        "city": {
          "id": "TUxBQ1ZJTGU4OGM3",
          "name": "Villa Gesell"
        },
        "state": {
          "id": "TUxBUENPU2ExMmFkMw",
          "name": "Bs.as. Costa Atlántica"
        },
        "country": {
          "id": "AR",
          "name": "Argentina"
        },
        "latitude": -37.2598939,
        "longitude": -56.9714194,
        "open_hours": ""
      },
      "geolocation": {
        "latitude": -37.2598939,
        "longitude": -56.9714194
      },
      "coverage_areas": [
      ],
      "attributes": [
        {
          "id": "CAPPERSO",
          "name": "Capacidad de personas",
          "value_id": "CAPPERSO-5",
          "value_name": "5",
          "attribute_group_id": "ADICIONALES",
          "attribute_group_name": "Adicionales"
        },
        {
          "id": "CKECKIN",
          "name": "Check in",
          "value_id": "CKECKIN-11:00",
          "value_name": "11:00",
          "attribute_group_id": "ADICIONALES",
          "attribute_group_name": "Adicionales"
        },
        {
          "id": "CKECKOUT",
          "name": "Check out",
          "value_id": "CKECKOUT-09:00",
          "value_name": "09:00",
          "attribute_group_id": "ADICIONALES",
          "attribute_group_name": "Adicionales"
        },
        {
          "id": "FECHADESDE",
          "name": "Desde",
          "value_id": "",
          "value_name": "1 de nero",
          "attribute_group_id": "ADICIONALES",
          "attribute_group_name": "Adicionales"
        },
        {
          "id": "FECHAHASTA",
          "name": "Hasta",
          "value_id": "",
          "value_name": "TODO EL AÑO",
          "attribute_group_id": "ADICIONALES",
          "attribute_group_name": "Adicionales"
        },
        {
          "id": "MLA50283-CUADRCENT",
          "name": "A cuantas cuadras del centro",
          "value_id": "MLA50283-CUADRCENT-1",
          "value_name": "1",
          "attribute_group_id": "ADICIONALES",
          "attribute_group_name": "Adicionales"
        },
        {
          "id": "MLA50283-CUADRMAR",
          "name": "A cuantas cuadras del mar",
          "value_id": "MLA50283-CUADRMAR-4",
          "value_name": "4",
          "attribute_group_id": "ADICIONALES",
          "attribute_group_name": "Adicionales"
        },
        {
          "id": "MLA50283-NUMVAJI",
          "name": "Vajilla para # de personas",
          "value_id": "MLA50283-NUMVAJI-6",
          "value_name": "6",
          "attribute_group_id": "ADICIONALES",
          "attribute_group_name": "Adicionales"
        },
        {
          "id": "MLA50283-SEÑA",
          "name": "% de seña",
          "value_id": "MLA50283-SEÑA-MAS-DE-50%",
          "value_name": "Más de 50%",
          "attribute_group_id": "ADICIONALES",
          "attribute_group_name": "Adicionales"
        },
        {
          "id": "NUMEROCAMA",
          "name": "Número de camas",
          "value_id": "NUMEROCAMA-6",
          "value_name": "6",
          "attribute_group_id": "ADICIONALES",
          "attribute_group_name": "Adicionales"
        },
        {
          "id": "PERIOTEMPO",
          "name": "Estadía Mínima",
          "value_id": "PERIOTEMPO-15",
          "value_name": "15",
          "attribute_group_id": "ADICIONALES",
          "attribute_group_name": "Adicionales"
        },
        {
          "id": "TIPOHABITA",
          "name": "Tipo de habitación",
          "value_id": "TIPOHABITA-HABPRIVA",
          "value_name": "Habitación privada",
          "attribute_group_id": "ADICIONALES",
          "attribute_group_name": "Adicionales"
        },
        {
          "id": "BALTERR",
          "name": "Balcón",
          "value_id": "BALTERR-N",
          "value_name": "No",
          "attribute_group_id": "AMBIENTES",
          "attribute_group_name": "Ambientes"
        },
        {
          "id": "COCI",
          "name": "Cocina",
          "value_id": "COCI-Y",
          "value_name": "Si",
          "attribute_group_id": "AMBIENTES",
          "attribute_group_name": "Ambientes"
        },
        {
          "id": "COME",
          "name": "Comedor diario",
          "value_id": "COME-Y",
          "value_name": "Si",
          "attribute_group_id": "AMBIENTES",
          "attribute_group_name": "Ambientes"
        },
        {
          "id": "DEPSERV",
          "name": "Dependencia de servicio",
          "value_id": "DEPSERV-N",
          "value_name": "No",
          "attribute_group_id": "AMBIENTES",
          "attribute_group_name": "Ambientes"
        },
        {
          "id": "DORMSUIT",
          "name": "Dormitorio en suite",
          "value_id": "DORMSUIT-Y",
          "value_name": "Si",
          "attribute_group_id": "AMBIENTES",
          "attribute_group_name": "Ambientes"
        },
        {
          "id": "ESCRITORIO",
          "name": "Escritorio",
          "value_id": "ESCRITORIO-N",
          "value_name": "No",
          "attribute_group_id": "AMBIENTES",
          "attribute_group_name": "Ambientes"
        },
        {
          "id": "ESTAR",
          "name": "Estar",
          "value_id": "ESTAR-N",
          "value_name": "No",
          "attribute_group_id": "AMBIENTES",
          "attribute_group_name": "Ambientes"
        },
        {
          "id": "LAVA",
          "name": "Lavadero",
          "value_id": "LAVA-Y",
          "value_name": "Si",
          "attribute_group_id": "AMBIENTES",
          "attribute_group_name": "Ambientes"
        },
        {
          "id": "LIVCOM",
          "name": "Living comedor",
          "value_id": "LIVCOM-Y",
          "value_name": "Si",
          "attribute_group_id": "AMBIENTES",
          "attribute_group_name": "Ambientes"
        },
        {
          "id": "LIVI",
          "name": "Living",
          "value_id": "LIVI-N",
          "value_name": "No",
          "attribute_group_id": "AMBIENTES",
          "attribute_group_name": "Ambientes"
        },
        {
          "id": "PAT",
          "name": "Patio",
          "value_id": "PAT-Y",
          "value_name": "Si",
          "attribute_group_id": "AMBIENTES",
          "attribute_group_name": "Ambientes"
        },
        {
          "id": "PLAYROOM",
          "name": "Playroom",
          "value_id": "PLAYROOM-N",
          "value_name": "No",
          "attribute_group_id": "AMBIENTES",
          "attribute_group_name": "Ambientes"
        },
        {
          "id": "TERRA",
          "name": "Terraza",
          "value_id": "TERRA-N",
          "value_name": "No",
          "attribute_group_id": "AMBIENTES",
          "attribute_group_name": "Ambientes"
        },
        {
          "id": "TOIL",
          "name": "Toilette",
          "value_id": "TOIL-N",
          "value_name": "No",
          "attribute_group_id": "AMBIENTES",
          "attribute_group_name": "Ambientes"
        },
        {
          "id": "VEST",
          "name": "Vestidor",
          "value_id": "VEST-N",
          "value_name": "No",
          "attribute_group_id": "AMBIENTES",
          "attribute_group_name": "Ambientes"
        },
        {
          "id": "AIRCEN",
          "name": "Aire acondicionado",
          "value_id": "AIRCEN-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "AMOBL",
          "name": "Amoblado",
          "value_id": "AMOBL-Y",
          "value_name": "Si",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "APTOFAMILY",
          "name": "Apto para familias/niños",
          "value_id": "APTOFAMILY-Y",
          "value_name": "Si",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "APTOFUMA",
          "name": "Apto para fumadores",
          "value_id": "APTOFUMA-Y",
          "value_name": "Si",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "BAR",
          "name": "Bar",
          "value_id": "BAR-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "CAJASEG",
          "name": "Caja de seguridad",
          "value_id": "CAJASEG-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "CALCEN",
          "name": "Calefacción",
          "value_id": "CALCEN-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "CANCHAGOLF",
          "name": "Cancha de golf",
          "value_id": "CANCHAGOLF-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "CANCHAPADD",
          "name": "Cancha de paddle",
          "value_id": "CANCHAPADD-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "CANFUT",
          "name": "Cancha de fútbol",
          "value_id": "CANFUT-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "CONINT",
          "name": "Conexión a internet",
          "value_id": "CONINT-Y",
          "value_name": "Si",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "DESAYUNOINCLU",
          "name": "Desayuno incluido",
          "value_id": "DESAYUNOINCLU-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "ESTACIOINCLU",
          "name": "Estacionamiento",
          "value_id": "ESTACIOINCLU-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "HIDRO",
          "name": "Hidromasaje",
          "value_id": "HIDRO-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "JARD",
          "name": "Jardín",
          "value_id": "JARD-Y",
          "value_name": "Si",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "LAVASECA",
          "name": "Lavarropa/Secarropa",
          "value_id": "LAVASECA-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "MLA50283-CALE",
          "name": "Calefón",
          "value_id": "MLA50283-CALE-Y",
          "value_name": "Si",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "MLA50283-DEPOGA",
          "name": "Depósito en garantía $",
          "value_id": "",
          "value_name": "3000",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "MLA50283-DVD",
          "name": "DVD",
          "value_id": "MLA50283-DVD-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "MLA50283-GASNAT",
          "name": "Gas natural",
          "value_id": "MLA50283-GASNAT-Y",
          "value_name": "Si",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "MLA50283-ROPABL",
          "name": "Ropa blanca",
          "value_id": "MLA50283-ROPABL-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "MLA50283-TERMO",
          "name": "Termotanque",
          "value_id": "MLA50283-TERMO-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "MLA50283-VENTITE",
          "name": "Ventilador de techo",
          "value_id": "MLA50283-VENTITE-Y",
          "value_name": "Si",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "PARR",
          "name": "Parrilla",
          "value_id": "PARR-Y",
          "value_name": "Si",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "PERMIMASCO",
          "name": "Permite mascotas",
          "value_id": "PERMIMASCO-Y",
          "value_name": "Si",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "PHONETEPAN",
          "name": "Linea telefónica",
          "value_id": "PHONETEPAN-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "PILNAT",
          "name": "Pileta",
          "value_id": "PILNAT-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "QUINCHO",
          "name": "Quincho",
          "value_id": "QUINCHO-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "RESTAUR",
          "name": "Restaurante",
          "value_id": "RESTAUR-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "SAUNA",
          "name": "Sauna",
          "value_id": "SAUNA-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "SOLARI",
          "name": "Solarium",
          "value_id": "SOLARI-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "SOM",
          "name": "SUM",
          "value_id": "SOM-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "SPA",
          "name": "Spa",
          "value_id": "SPA-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "TVXCABLE",
          "name": "TV por cable",
          "value_id": "TVXCABLE-Y",
          "value_name": "Si",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "VIGI",
          "name": "Seguridad",
          "value_id": "VIGI-N",
          "value_name": "No",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "WIFI",
          "name": "Wifi",
          "value_id": "WIFI-Y",
          "value_name": "Si",
          "attribute_group_id": "COMODIDADES",
          "attribute_group_name": "Comodidades"
        },
        {
          "id": "MLA1459-HORPREF",
          "name": "Horario de contacto",
          "value_id": "",
          "value_name": "de 8 a 22",
          "attribute_group_id": "FIND",
          "attribute_group_name": "Ficha técnica"
        },
        {
          "id": "MLA1459-INMUEBLE",
          "name": "Inmueble",
          "value_id": "MLA1459-INMUEBLE-OTRO_INMUEBLE",
          "value_name": "Otros Inmuebles",
          "attribute_group_id": "FIND",
          "attribute_group_name": "Ficha técnica"
        },
        {
          "id": "MLA1459-OPERACION",
          "name": "Operación",
          "value_id": "MLA1459-OPERACION-ALQUILER_DE_TEMPORADA",
          "value_name": "Alquiler Temporario",
          "attribute_group_id": "FIND",
          "attribute_group_name": "Ficha técnica"
        },
        {
          "id": "MLA1892-ANTIG",
          "name": "Antigüedad",
          "value_id": "MLA1892-ANTIG-MAX_10_ANOS",
          "value_name": "Max 10 años",
          "attribute_group_id": "FIND",
          "attribute_group_name": "Ficha técnica"
        },
        {
          "id": "MLA1892-ESTADO",
          "name": "Estado",
          "value_id": "MLA1892-ESTADO-MUY_BUENO",
          "value_name": "Muy bueno",
          "attribute_group_id": "FIND",
          "attribute_group_name": "Ficha técnica"
        },
        {
          "id": "MLA1892-MTRS",
          "name": "Superficie cubierta (m²)",
          "value_id": "",
          "value_name": "35",
          "attribute_group_id": "FIND",
          "attribute_group_name": "Ficha técnica"
        },
        {
          "id": "MLA1892-MTRSTOTAL",
          "name": "Superficie total (m²)",
          "value_id": "",
          "value_name": "44",
          "attribute_group_id": "FIND",
          "attribute_group_name": "Ficha técnica"
        },
        {
          "id": "MLA1892-TIPOINMUEB",
          "name": "Tipo de inmueble",
          "value_id": "",
          "value_name": "petit hotel",
          "attribute_group_id": "FIND",
          "attribute_group_name": "Ficha técnica"
        }
      ],
      "warnings": [
      ],
      "listing_source": "",
      "variations": [
      ],
      "status": "active",
      "sub_status": [
      ],
      "tags": [
      ],
      "warranty": null,
      "catalog_product_id": null,
      "parent_item_id": null,
      "differential_pricing": null,
      "deal_ids": [
      ],
      "automatic_relist": false,
      "date_created": "2016-01-31T14:16:20.000Z",
      "last_updated": "2016-02-01T05:46:48.000Z"
    }


    There’s a lot of information in the Json response. Below you’ll find some important guidelines.

    Defining attributes

    You must know some of the fields are mandatory when you create a Json for your item, while some others can be skipped or will be automatically added by us.They will define how the item is displayed and the position on search results.

    Title

    On classified items, even though you can send a title that’s gonna be displayed on the item details page, users who are browsing classifieds will see on the list a titled that’s generated by us basing on the attributes you setted on the item.

    Description

    A detailed description will improve your chances to rent or buy your property and will save you time from answering unnecessary question. It can be a text-only description or you can add your own personalized HTML. If you are interested in increasing your knowledge about this topic, check our item description guide.

    Pictures

    Good pictures can make your property more appealing and give other users a better idea of how it looks like. Basically, you should add an array of up to six URL pictures on the Json.

     {
     ....
     "pictures":[
      {"source":"http://yourServer/path/to/your/picture.jpg"},
      {"source":"http://yourServer/path/to/your/otherPicture.gif"},
      {"source":"http://yourServer/path/to/your/anotherPicture.png"}
     ]
     ...
    }



    We highly recommend not to use slow servers to host your pictures since this can lead to disadvantages when listing.
    You can also add or change pictures to your item later on, please read more about this topic to know which kind of pictures are allowed and how to work with them on our Working with pictures guide.

    Category & attributes

    Sellers must define a category in MercadoLibre site. This attribute is mandatory and only accepts pre-established ids. Each category has it’s own attributes for you to work with. To get the details see our Categories guide.

    {
     ....
      "category_id":"MLA12683",
     ...
    }


    Price

    Price is mandatory, if you’re open to negotiate the price for rent or sale with other users you can set it as to be agreed.

    Currency

    This one is a mandatory attribute. You need to define it using a pre-established id. You’ll find available currency ids calling the category where you want to list your item. Learn how by following our category guide.

    Seller Custom Field

    The seller custom field is not mandatory but is very useful since there aren’t any pre-established values and you can send anything as a String. Most sellers use this field to associate their own SKUs to their products, to identify the product sold on the order.
    Example:

    curl -X PUT -d '{"seller_custom_field": "21000093"}' https://api.mercadolibre.com/items/MLA599074368?access_token=¢ACCESS_TOKEN

    Listing types

    This is another case of a mandatory attribute that only accepts pre-defined values and is very important for you to understand about it.
    There are different listing types available for each site. You should make a mixed call through sites and listing_types resources to know which listing_types are supported. Follow our guide to know which listing type will suite your property best.

    List a real estate property

    You’re ready to list your first classified item. Notice you’ll need an access_token to make it. If you have questions regarding how to get your access token, please go back to the Getting Started tutorial. In addition, we highly recommended you validate the Json you’re sending before making a POST, so you better check out this really easy and quick item validation tutorial.
    You can create a Json for your item basing on the following example, or just send it and you’ll be listing a sample product on the site:

    curl -X POST -H "Content-Type: application/json" -d {
    "title": "Property title",
    "category_id": "MLA401686",
    "price": 100000,
    "currency_id": "ARS",
    "available_quantity": 1,
    "buying_mode": "classified",
    "listing_type_id": "silver",
    "condition": "not_specified",
    "pictures": [
    {
    "source":"http://mla-d2-p.mlstatic.com/item-de-test-no-ofertar-543605-MLA25041518406_092016-O.jpg?square=false"
    }
    ],
    "seller_contact": {
    "contact": "Contact name",
    "other_info": "Additional contact info",
    "area_code": "011",
    "phone": "4444-5555",
    "area_code2": "",
    "phone2": "",
    "email": "contact-email@somedomain.com",
    "webmail": ""
    },
    "location": {
    "address_line": "My property address 1234",
    "zip_code": "01234567",
    "neighborhood": {
    "id": "TUxBQlBBUzgyNjBa"
    },
    "latitude": -34.48755,
    "longitude": -58.56987
    },
    "attributes": [
    {
    "id": "ROOMS",
    "value_name": "2"
    },
    {
    "id": "FULL_BATHROOMS",
    "value_name": "1"
    },
    {
    "id": "PARKING_LOTS",
    "value_name": "1"
    },
    {
    "id": "BEDROOMS",
    "value_name": "4"
    },
    {
    "id": "COVERED_AREA",
    "value_name": "30 m²"
    },
    {
    "id": "TOTAL_AREA",
    "value_name": "40 m²"
    }
    ],
    "description": "This is the real estate property descritpion."
    }
    https://api.mercadolibre.com/items?access_token=$ACCESS_TOKEN



    Next topic: Sync your listings.

    Please rate this

Manage packages

Promotions Packs are listing packages for Car Dealers and Real State Agency Classifieds listings. In this tutorial you’ll learn how to get information about packages and also engage and activate a package.

Contents:

  • Obtain packages by category
  • Get packages engaged by an user
  • Resource description
  • Calling packages
  • Obtain listing Packages and upgrades
  • Hired packages by user
  • Calling packages
  • Hire a package
  • Activate a hired package
  • End a hired package
  • Calls to upgrades
  • GET upgrades by user
  • Check item available upgrades
  • Upgrade the item
  • Downgrade an item
  • End Package
  • FAQ

Obtain packages by category

The possible values for classifieds_promotion_packs categories are different each site. Possible values are:
{site_id}1743: Car Dealer.
{site_id}1459: Real Estate Agency.
For example, on Argentina, Car Dealer package category it’s MLA1743 while in Brazil it’s MLB1743
Make a GET to look for packages in an specific category:

curl -X GET https://api.mercadolibre.com/categories/{category_id}/classifieds_promotion_packs

Response:

[
  {
    "id": "IPAA",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 15 Básico",
    "price": 350,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCAA",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 15
      }
    ]
  },
  {
    "id": "IPAR",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 15 Premium",
    "price": 600,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCAR",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "gold",
        "available_listings": 6
      },
      {
        "listing_type_id": "gold_premium",
        "available_listings": 1
      },
      {
        "listing_type_id": "silver",
        "available_listings": 8
      }
    ]
  },
  {
    "id": "IPAS",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 15 Especial",
    "price": 410,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCAS",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 10
      },
      {
        "listing_type_id": "gold",
        "available_listings": 5
      }
    ]
  },
  {
    "id": "IPBA",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 30 Básico",
    "price": 480,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCBA",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 30
      }
    ]
  },
  {
    "id": "IPBR",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 30 Premium",
    "price": 880,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCBR",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 16
      },
      {
        "listing_type_id": "gold_premium",
        "available_listings": 2
      },
      {
        "listing_type_id": "gold",
        "available_listings": 12
      }
    ]
  },
  {
    "id": "IPBS",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 30 Especial",
    "price": 560,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCBS",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 20
      },
      {
        "listing_type_id": "gold",
        "available_listings": 10
      }
    ]
  },
  {
    "id": "IPCA",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 60 Básico",
    "price": 570,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCCA",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 60
      }
    ]
  },
  {
    "id": "IPCR",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 60 Premium",
    "price": 910,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCCR",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 32
      },
      {
        "listing_type_id": "gold",
        "available_listings": 24
      },
      {
        "listing_type_id": "gold_premium",
        "available_listings": 4
      }
    ]
  },
  {
    "id": "IPCS",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 60 Especial",
    "price": 650,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCCS",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "gold",
        "available_listings": 20
      },
      {
        "listing_type_id": "silver",
        "available_listings": 40
      }
    ]
  },
  {
    "id": "IPDA",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 100 Básico",
    "price": 750,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCDA",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 100
      }
    ]
  },
  {
    "id": "IPDR",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 100 Premium",
    "price": 1180,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCDR",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "gold_premium",
        "available_listings": 5
      },
      {
        "listing_type_id": "gold",
        "available_listings": 35
      },
      {
        "listing_type_id": "silver",
        "available_listings": 60
      }
    ]
  },
  {
    "id": "IPDS",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 100 Especial",
    "price": 820,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCDS",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "gold",
        "available_listings": 25
      },
      {
        "listing_type_id": "silver",
        "available_listings": 75
      }
    ]
  },
  {
    "id": "IPEA",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 500 Básico",
    "price": 850,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCEA",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "silver",
        "available_listings": 500
      }
    ]
  },
  {
    "id": "IPER",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 500 Premium",
    "price": 1900,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCER",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "gold",
        "available_listings": 100
      },
      {
        "listing_type_id": "gold_premium",
        "available_listings": 15
      },
      {
        "listing_type_id": "silver",
        "available_listings": 385
      }
    ]
  },
  {
    "id": "IPES",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete 500 Especial",
    "price": 1000,
    "package_type": "rotary",
    "duration": 30,
    "status": "active",
    "charge_type_id": "CCES",
    "max_upgrades": 0,
    "listing_details": [
      {
        "listing_type_id": "gold",
        "available_listings": 70
      },
      {
        "listing_type_id": "silver",
        "available_listings": 430
      }
    ]
  }
]

Get packages engaged by an user

curl -X GET https://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs?access_token=$ACCESS_TOKEN;

Response:

[
	{
    	"id": 754985,
    	"user_id": "135146148",
    	"promotion_pack_id": "MPAB",
    	"category_id": "MLU1743",
    	"description": "Paquete 15 Básico",
    	"package_type": "rotary",
    	"status": "active",
    	"date_created": "2013-05-23T15:34:48.498-04:00",
    	"date_start": "2013-05-23T15:34:47.544-04:00",
    	"date_expires": "2013-06-22T15:34:47.544-04:00",
    	"date_stopped": null,
    	"last_updated": "2013-05-23T15:35:48.211-04:00",
    	"engagement_type": "none",
    	"charge_id": 822129921,
    	"remaining_listings": 15,
    	"used_listings": 0,
    	"listing_details": [
        	{
            	"listing_type_id": "silver",
            	"available_listings": 15,
            	"used_listings": 0,
            	"remaining_listings": 15
        	}
    	]
	}
]

Resource description

attribute description
id unique package identifier.
user_id unique id of the user who engaged the package.
category_id Package category.
description package name.
package_type: package detail.
status package status possible values are:
active: the user can use this package to list. An available_listing will be discounted when he does.
pending: the package it’s not active yet.
finished: expired package.
date_created date the package was created.
date_start: date the package was activated.
date_expires date the package expires.
date_stopped date the package was finished.
last_updated last time the package was updated.
engagement_type Possible values are:
“none”: The package was engaged for one time.
“re-engagement”: When the package expires, a similar package_type will be re engaged automatically.
charge_id unique id of the charge generated over the engagement of the package.
listing_details detailed information about listing types and availability.
listing_type_id listing_type associated to the package.
available_listings amount of listings the user gets with the package.
used_listings already spent listings.
remaining_listings available listings left.

Check if an user has an specific listing_type available

curl -X GET https://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs/{listing_type}ilver& categoryId={Category_id}?access_token=$ACCESS_TOKEN

Response:

{
  "has_available_listings": true
}

Engage and activate a package

You can engage a package and activate it by making a POST to the API like in the following example:

curl -X POST "Content-type:application/json" -d '{
"categ_id":"MLA1459", "promotion_pack_id":"IPIN", "engagement_type":"none", "status":"active"
}' https://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs&access_token=$ACCESS_TOKEN

The current documentation focusses on the new logic for upgrades packages currently working only for real estate agencies for Argentina, Brazil, Mexico and Uruguay. The new upgrade packages logic consists in migrating the actual model where charges are being generated for individual upgrades, to an analog logic on listings packages where the client hires an upgrade package and then every upgrade done occupies a place or quota in the package.

Calling packages

There’s retro compatibility between the existing packages logic and the new one, adding an extra optional filter on the call: “package_content” that makes possible to differentiate between listing packages and upgrade packages.

Obtain listing Packages and upgrades

curl -X GET https://api.mercadolibre.com/categories/{category_id}/classifieds_promotion_packs

Example:

https://api.mercadolibre.com/categories/MLA1459/classifieds_promotion_packs?package_content=upgrades,publications
[
    {
        "id": "IPUA",
        "category_id": "MLA1459",
        "brand": "MLREALESTATE",
        "description": "Paquete Unico Ilimitado 15",
        "price": 600,
        "package_type": "unlimited",
        "package_content": "publications",
        "duration": 30,
        "status": "active",
        "charge_type_id": "CCBA",
        "max_upgrades": 12,
        "listing_details": [
            {
                "listing_type_id": "silver",
                "available_listings": 15
            }
        ],
        "visibility": "private"
    },
    {
        "id": "IPUB",
        "category_id": "MLA1459",
        "brand": "MLREALESTATE",
        "description": "Paquete Unico Ilimitado 50",
        "price": 600,
        "package_type": "unlimited",
        "package_content": "publications",
        "duration": 30,
        "status": "active",
        "charge_type_id": "CCBA",
        "max_upgrades": 30,
        "listing_details": [
            {
                "listing_type_id": "silver",
                "available_listings": 50
            }
        ],
        "visibility": "private"
    },
    {
        "id": "IPUC",
        "category_id": "MLA1459",
        "brand": "MLREALESTATE",
        "description": "Paquete Unico Ilimitado 100",
        "price": 600,
        "package_type": "unlimited",
        "package_content": "publications",
        "duration": 30,
        "status": "active",
        "charge_type_id": "CCBA",
        "max_upgrades": 50,
        "listing_details": [
            {
                "listing_type_id": "silver",
                "available_listings": 100
            }
        ],
        "visibility": "private"
    },
    {
        "id": "IPUD",
        "category_id": "MLA1459",
        "brand": "MLREALESTATE",
        "description": "Paquete Unico Ilimitado 500",
        "price": 600,
        "package_type": "unlimited",
        "package_content": "publications",
        "duration": 30,
        "status": "active",
        "charge_type_id": "CCBA",
        "max_upgrades": 100,
        "listing_details": [
            {
                "listing_type_id": "silver",
                "available_listings": 500
            }
        ],
        "visibility": "private"
    },
    {
        "id": "IPUPGG1",
        "category_id": "MLA1459",
        "brand": "MLREALESTATE",
        "description": "Paquete Upgrades Gold Individual",
        "price": 150,
        "package_type": "rotary",
        "package_content": "upgrades",
        "duration": 30,
        "status": "active",
        "charge_type_id": "free",
        "max_upgrades": 1,
        "listing_details": [
            {
                "listing_type_id": "gold",
                "available_listings": 1
            }
        ],
        "visibility": "private"
    },
    {
        "id": "IPUPGGP1",
        "category_id": "MLA1459",
        "brand": "MLREALESTATE",
        "description": "Paquete Upgrades Gold Premium Individual",
        "price": 220,
        "package_type": "rotary",
        "package_content": "upgrades",
        "duration": 30,
        "status": "active",
        "charge_type_id": "free",
        "max_upgrades": 1,
        "listing_details": [
            {
                "listing_type_id": "gold_premium",
                "available_listings": 1
            }
        ],
        "visibility": "private"
    },
    {
        "id": "IPUPGGP10",
        "category_id": "MLA1459",
        "brand": "MLREALESTATE",
        "description": "Paquete Upgrades 10 Destaques Gold Premium",
        "price": 1650,
        "package_type": "rotary",
        "package_content": "upgrades",
        "duration": 30,
        "status": "active",
        "charge_type_id": "free",
        "max_upgrades": 1,
        "listing_details": [
            {
                "listing_type_id": "gold_premium",
                "available_listings": 10
            }
        ],
        "visibility": "private"
    }
]

As you see, we got the listing packages and upgrade packages for the specified category.

Hired packages by user

GET https://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs?access_token=

Example:

https://api.mercadolibre.com/users/184179005/classifieds_promotion_packs?access_token=$ACCESS_TOKEN&status=active,finished&package_content=upgrades,publications
[
    {
        "id": 1024029,
        "user_id": "184179005",
        "promotion_pack_id": "PPUGOLDPREMIUMTEST02",
        "category_id": "MLA1459",
        "brand": "MLREALESTATE",
        "description": "Paquete de upgrades gold premium",
        "package_type": "rotary",
        "status": "active",
        "date_created": "2015-05-27T14:26:37.790-04:00",
        "date_start": "2015-05-27T14:26:37.692-04:00",
        "date_expires": "2015-06-27T14:26:37.692-04:00",
        "date_stopped": null,
        "last_updated": "2015-05-27T14:26:37.790-04:00",
        "engagement_type": "re-engagement",
        "package_content": "upgrades",
        "charge_id": 0,
        "remaining_listings": 9999,
        "used_listings": 1,
        "listing_details": [
            {
                "listing_type_id": "gold_premium",
                "available_listings": 10000,
                "used_listings": 1,
                "remaining_listings": 9999
            }
        ]
    },
    {
        "id": 1023654,
        "user_id": "184179005",
        "promotion_pack_id": "IPUE",
        "category_id": "MLA1459",
        "brand": "MLREALESTATE",
        "description": "Paquete Unico Ilimitado 1000",
        "package_type": "unlimited",
        "status": "active",
        "date_created": "2015-05-26T14:37:12.540-04:00",
        "date_start": "2015-05-26T14:37:12.475-04:00",
        "date_expires": "2015-06-26T14:37:12.475-04:00",
        "date_stopped": null,
        "last_updated": "2015-05-27T14:23:02.951-04:00",
        "engagement_type": "none",
        "package_content": "publications",
        "charge_id": 1725523903,
        "remaining_listings": 999,
        "used_listings": 1,
        "listing_details": [
            {
                "listing_type_id": "silver",
                "available_listings": 1000,
                "used_listings": 1,
                "remaining_listings": 999
            }
        ]
    }
]

As you see we got a upgrade package and a listing package. You can see the difference in the package_content attribute.
Note: Due to retro-compatibility, if package_content parameter is not provided in the request, it will be equal to provide package_content =publications. This means, that every time you want to obtain upgrade packages, you need to include “upgrades” in the package_content parameter.

Calling packages

Example:

https://api.mercadolibre.com/users/184179005/classifieds_promotion_packs?access_token=$ACCESS_TOKEN&status=active,finished&package_content=upgrades,publications

Response in case there’s no package:

[
    {
"message":"User promotion packs not found for user 184179005",
"error":"not_found",
"status":404,
"cause":[]
     }

]

Hire a package

Example:

POST https://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs?access_token=$ACCESS_TOKEN

BODY WITHOUT AUTOMATIC RE-ENGAGEMENT:

{ 
“status”:”active”,
“engagement_type”:”none”,
“promotion_pack_id”:”IPIN”,
“categ_id”:”MLA1743” 
}

Example:

 curl -X POST --header "Content-type:application/json" -d 
'{"promotion_pack_id":"PPUGOLDPREMIUMTEST02","categ_id":"MLA1459","engagement_type":"re-engagement","status":"active"}' 'https://api.mercadolibre.com/users/184179005/classifieds_promotion_packs?access_token=$ACCESS_TOKEN'


   "id": 1026038,
    "user_id": "184179005",
    "promotion_pack_id": "PPUGOLDPREMIUMTEST02",
    "category_id": "MLA1459",
    "brand": "MLREALESTATE",
    "description": "Paquete de upgrades gold premium",
    "package_type": "rotary",
    "status": "active",
    "date_created": "2015-06-03T16:37:31.646-04:00",
    "date_start": "2015-06-03T16:37:31.497-04:00",
    "date_expires": "2015-07-03T16:37:31.497-04:00",
    "date_stopped": null,
    "last_updated": "2015-06-03T16:37:31.646-04:00",
    "engagement_type": "re-engagement",
    "package_content": "upgrades",
    "charge_id": 0,
    "remaining_listings": 10000,
    "used_listings": 0,
    "listing_details": [
        {
            "listing_type_id": "gold_premium",
            "available_listings": 10000,
            "used_listings": 0,
            "remaining_listings": 10000
        }
    ]
}

As you can see, it returns the hired package. In this case is an upgrade packages.
NOTE: On contrary of listing packages, upgrade packages does not accept “pending” as inicial status.
Example:

 curl -X POST --header "Content-type:application/json" -d '{"promotion_pack_id":"PPUGOLDPREMIUMTEST02","categ_id":"MLA1459","engagement_type":"re-engagement","status":"active"}' 'https://api.mercadolibre.com/users/184179005/classifieds_promotion_packs?access_token=$ACCESS_TOKEN'

Response in case you can’t hire the package:

 {
    "message": "Promotion pack not found for categ MLA1459 and id PPUGOLDPREMIUMTEST02",
    "error": "not_found",
    "status": 404,
    "cause": []
}

Activate a hired package

Example:

PUT https://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs/{user_promotion_pack_id}?access_token=$ACCESS_TOKEN
BODY
{ “status”:”active” }

To obtain the package_id we’ll make the following GET:

GET https://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs?status=pending

End a hired package

Example:

PUT https://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs/{user_promotion_pack_id}?acces_token=$ACCESS_TOKEN
BODY
{ “status”:”finished” }

Calls to upgrades

If the user doesn’t have hired any upgrade package, the upgrade is not going to be done.

GET upgrades by user

Example:

GET https://api.mercadolibre.com/users/{user_id}/classifieds_promotion_packs/user_item_upgrade
?acces_token=$ACCESS_TOKEN

Response:

curl -X GET 'https://api.mercadolibre.com/users/184179005/classifieds_promotion_packs/user_item_upgrade?status=finished,active&access_token=$ACCESS_TOKEN'
{
    "paging": {
        "total": 4,
        "offset": 0,
        "limit": 50
    },
    "results": [
        {
            "item_id": "MLA562766164",
            "listing_type_from": "silver",
            "listing_type_to": "gold_premium",
            "engagement_type": "none",
            "status": "active",
            "date_start": "2015-06-03T08:28:32.000-04:00",
            "date_stop": null,
            "date_expires": "2015-06-27T14:26:37.000-04:00",
            "charge_id": null
        },
        {
            "item_id": "MLA562083882",
            "listing_type_from": "silver",
            "listing_type_to": "gold_premium",
            "engagement_type": "none",
            "status": "active",
            "date_start": "2015-05-29T12:20:39.000-04:00",
            "date_stop": null,
            "date_expires": "2015-06-27T14:26:37.000-04:00",
            "charge_id": null
        },
        {
            "item_id": "MLA562083882",
            "listing_type_from": "silver",
            "listing_type_to": "gold_premium",
            "engagement_type": "none",
            "status": "finished",
            "date_start": "2015-04-29T11:49:06.000-04:00",
            "date_stop": "2015-05-29T11:50:41.000-04:00",
            "date_expires": "2015-06-27T14:26:37.000-04:00",
            "charge_id": null
        },
        {
            "item_id": "MLA561761811",
            "listing_type_from": "silver",
            "listing_type_to": "gold_premium",
            "engagement_type": "none",
            "status": "finished",
            "date_start": "2015-05-27T16:05:48.000-04:00",
            "date_stop": "2015-05-28T08:09:58.000-04:00",
            "date_expires": "2015-06-26T16:05:48.000-04:00",
            "charge_id": null
        }
    ]
}

As you see, this user hired 4 upgrades, 3 of them already ended. You can also see upgrades hired for the same item.
NOTE: According to this new logic, charge_id attribute will no longer be in use. The charges will apply to the package.

Check item available upgrades

GET https://api.mercadolibre.com/items/{item_id}/available_upgrades?access_token=$ACCESS_TOKEN

Example:

curl 'https://api.mercadolibre.com/items/MLA563672820/available_upgrades?&access_token=$ACCESS_TOKEN'
[
    {
        "site_id": "MLA",
        "id": "gold_premium",
        "name": "Oro Premium"
    },
    {
        "site_id": "MLA",
        "id": "gold",
        "name": "Oro"
    }
]

Upgrade the item

POST https://api.mercadolibre.com/items/{item_id}/listing_type?acces_token=$ACCESS_TOKEN
BODY
{ “id”:”{listing_type}” }

The response is the item updated.
Example:

curl -X POST --header "Content-type:application/json" -d '{"id":"gold"}' 'https://api.mercadolibre.com/items/MLA563940625/listing_type?access_token=$ACCESS_TOKEN'
{
    "id": "MLA563940625",
    "site_id": "MLA",
    "title": "Test 10 No Ofertar",
    "subtitle": null,
    "seller_id": 184854440,
    "category_id": "MLA50543",
    "official_store_id": null,
    "price": 2928282,
    "base_price": 2928282,
    "original_price": null,
    "currency_id": "ARS",
    "initial_quantity": 1,
    "available_quantity": 1,
    "sold_quantity": 0,
    "buying_mode": "classified",
    "listing_type_id": "gold",
    "start_time": "2015-06-09T20:25:50.000Z",
    "stop_time": "2015-07-05T19:51:17.587Z",
    "end_time": "2015-07-05T19:51:17.587Z",
    "condition": "not_specified",
    "permalink": "http://inmueble.mercadolibre.com.ar/MLA-563940625-test-10-no-ofertar-_JM",
    "thumbnail": "http://mla-s1-p.mlstatic.com/302401-MLA20317818801_062015-I.jpg",
    "secure_thumbnail": "https://mla-s1-p.mlstatic.com/302401-MLA20317818801_062015-I.jpg",
    "pictures": [
        {
            "id": "302401-MLA20317818801_062015",
            "url": "http://mla-s1-p.mlstatic.com/302401-MLA20317818801_062015-O.jpg",
            "secure_url": "https://mla-s1-p.mlstatic.com/302401-MLA20317818801_062015-O.jpg",
            "size": "500x281",
            "max_size": "1200x675",
            "quality": ""
        }
    ],
    "video_id": null,
    "descriptions": [],
    "accepts_mercadopago": false,
    "non_mercado_pago_payment_methods": [],
    "shipping": {
        "mode": "not_specified",
        "local_pick_up": false,
        "free_shipping": false,
        "methods": [],
        "dimensions": null,
        "tags": []
    },
    "international_delivery_mode": "none",
    "seller_address": {
        "id": 163310864,
        "comment": "",
        "address_line": "Test Address 123",
        "zip_code": "1414",
        "city": {
            "id": "",
            "name": "Palermo"
        },
        "state": {
            "id": "AR-C",
            "name": "Capital Federal"
        },
        "country": {
            "id": "AR",
            "name": "Argentina"
        },
        "latitude": "",
        "longitude": "",
        "search_location": {
            "neighborhood": {
                "id": "TUxBQlBBTDI1MTVa",
                "name": "Palermo"
            },
            "city": {
                "id": "TUxBQ0NBUGZlZG1sYQ",
                "name": "Capital Federal"
            },
            "state": {
                "id": "TUxBUENBUGw3M2E1",
                "name": "Capital Federal"
            }
        }
    },
    "seller_contact": {
        "contact": "",
        "other_info": "",
        "area_code": "",
        "phone": "",
        "area_code2": "",
        "phone2": "",
        "email": "",
        "webpage": ""
    },
    "location": {
        "address_line": "falsa 123 123",
        "zip_code": "",
        "neighborhood": {
            "id": "TUxBQkVTUDYyODRa",
            "name": "Espartillar"
        },
        "city": {
            "id": "TUxBQ0FETzQ2Nzc",
            "name": "Adolfo Alsina"
        },
        "state": {
            "id": "TUxBUFpPTmFpbnRl",
            "name": "Buenos Aires Interior"
        },
        "country": {
            "id": "AR",
            "name": "Argentina"
        },
        "latitude": -34.6635266,
        "longitude": -58.3654707,
        "open_hours": ""
    },
    "geolocation": {
        "latitude": -34.6635266,
        "longitude": -58.3654707
    },
    "coverage_areas": [],
    "attributes": [
        {
            "id": "MLA1459-HORPREF",
            "name": "Horario de contacto",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA50541-ACCESO",
            "name": "Acceso",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA50541-ANTIG",
            "name": "Antigüedad",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA50541-EXPENCEM",
            "name": "Expensas ($)",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA50541-SEGUR",
            "name": "Seguridad",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA1459-INMUEBLE",
            "name": "Inmueble",
            "value_id": "MLA1459-INMUEBLE-COCHERA",
            "value_name": "Cochera",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        },
        {
            "id": "MLA1459-OPERACION",
            "name": "Operación",
            "value_id": "MLA1459-OPERACION-VENTA",
            "value_name": "Venta",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        },
        {
            "id": "MLA50541-MTRSTOTAL",
            "name": "Superficie total (m²)",
            "value_id": "",
            "value_name": "24",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        },
        {
            "id": "MLA50541-TIPCOB",
            "name": "Tipo de cobertura",
            "value_id": "MLA50541-TIPCOB-CUBIERTA",
            "value_name": "Cubierta",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        },
        {
            "id": "MLA50541-TIPOCOCH",
            "name": "Tipo de cochera",
            "value_id": "MLA50541-TIPOCOCH-FIJA",
            "value_name": "Fija",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        }
    ],
    "listing_source": "",
    "variations": [],
    "status": "active",
    "sub_status": [],
    "tags": [],
    "warranty": null,
    "catalog_product_id": null,
    "seller_custom_field": null,
    "parent_item_id": null,
    "differential_pricing": null,
    "deal_ids": [],
    "automatic_relist": false,
    "date_created": "2015-06-09T20:25:50.000Z",
    "last_updated": "2015-06-10T12:20:32.418Z"
}

Downgrade an item

POST https://api.mercadolibre.com/items/{item_id}/listing_type?acces_token=$ACCESS_TOKEN
BODY
{ “id”:”{listing_type}” }

The difference is the that the value for the “id” on the JSON is going to be the one for the original listing_type. For example, if you made an upgrade from “silver” to “gold”, the id you’re sending on the call (downgrade) is going to be “silver”.
Example:

curl -X POST --header "Content-type:application/json" -d '{"id":"silver"}' 'https://api.mercadolibre.com/items/MLA563940625/listing_type?access_token=$ACCESS_TOKEN'
{
    "id": "MLA563940625",
    "site_id": "MLA",
    "title": "Test 10 No Ofertar",
    "subtitle": null,
    "seller_id": 184854440,
    "category_id": "MLA50543",
    "official_store_id": null,
    "price": 2928282,
    "base_price": 2928282,
    "original_price": null,
    "currency_id": "ARS",
    "initial_quantity": 1,
    "available_quantity": 1,
    "sold_quantity": 0,
    "buying_mode": "classified",
    "listing_type_id": "silver",
    "start_time": "2015-06-09T20:25:50.000Z",
    "stop_time": "2015-07-05T19:51:17.587Z",
    "end_time": "2015-07-05T19:51:17.587Z",
    "condition": "not_specified",
    "permalink": "http://inmueble.mercadolibre.com.ar/MLA-563940625-test-10-no-ofertar-_JM",
    "thumbnail": "http://mla-s1-p.mlstatic.com/302401-MLA20317818801_062015-I.jpg",
    "secure_thumbnail": "https://mla-s1-p.mlstatic.com/302401-MLA20317818801_062015-I.jpg",
    "pictures": [
        {
            "id": "302401-MLA20317818801_062015",
            "url": "http://mla-s1-p.mlstatic.com/302401-MLA20317818801_062015-O.jpg",
            "secure_url": "https://mla-s1-p.mlstatic.com/302401-MLA20317818801_062015-O.jpg",
            "size": "500x281",
            "max_size": "1200x675",
            "quality": ""
        }
    ],
    "video_id": null,
    "descriptions": [],
    "accepts_mercadopago": false,
    "non_mercado_pago_payment_methods": [],
    "shipping": {
        "mode": "not_specified",
        "local_pick_up": false,
        "free_shipping": false,
        "methods": [],
        "dimensions": null,
        "tags": []
    },
    "international_delivery_mode": "none",
    "seller_address": {
        "id": 163310864,
        "comment": "",
        "address_line": "Test Address 123",
        "zip_code": "1414",
        "city": {
            "id": "",
            "name": "Palermo"
        },
        "state": {
            "id": "AR-C",
            "name": "Capital Federal"
        },
        "country": {
            "id": "AR",
            "name": "Argentina"
        },
        "latitude": "",
        "longitude": "",
        "search_location": {
            "neighborhood": {
                "id": "TUxBQlBBTDI1MTVa",
                "name": "Palermo"
            },
            "city": {
                "id": "TUxBQ0NBUGZlZG1sYQ",
                "name": "Capital Federal"
            },
            "state": {
                "id": "TUxBUENBUGw3M2E1",
                "name": "Capital Federal"
            }
        }
    },
    "seller_contact": {
        "contact": "",
        "other_info": "",
        "area_code": "",
        "phone": "",
        "area_code2": "",
        "phone2": "",
        "email": "",
        "webpage": ""
    },
    "location": {
        "address_line": "falsa 123 123",
        "zip_code": "",
        "neighborhood": {
            "id": "TUxBQkVTUDYyODRa",
            "name": "Espartillar"
        },
        "city": {
            "id": "TUxBQ0FETzQ2Nzc",
            "name": "Adolfo Alsina"
        },
        "state": {
            "id": "TUxBUFpPTmFpbnRl",
            "name": "Buenos Aires Interior"
        },
        "country": {
            "id": "AR",
            "name": "Argentina"
        },
        "latitude": -34.6635266,
        "longitude": -58.3654707,
        "open_hours": ""
    },
    "geolocation": {
        "latitude": -34.6635266,
        "longitude": -58.3654707
    },
    "coverage_areas": [],
    "attributes": [
        {
            "id": "MLA1459-HORPREF",
            "name": "Horario de contacto",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA50541-ACCESO",
            "name": "Acceso",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA50541-ANTIG",
            "name": "Antigüedad",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA50541-EXPENCEM",
            "name": "Expensas ($)",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA50541-SEGUR",
            "name": "Seguridad",
            "value_id": "",
            "value_name": "",
            "attribute_group_id": "ADICIONALES",
            "attribute_group_name": "Adicionales"
        },
        {
            "id": "MLA1459-INMUEBLE",
            "name": "Inmueble",
            "value_id": "MLA1459-INMUEBLE-COCHERA",
            "value_name": "Cochera",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        },
        {
            "id": "MLA1459-OPERACION",
            "name": "Operación",
            "value_id": "MLA1459-OPERACION-VENTA",
            "value_name": "Venta",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        },
        {
            "id": "MLA50541-MTRSTOTAL",
            "name": "Superficie total (m²)",
            "value_id": "",
            "value_name": "24",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        },
        {
            "id": "MLA50541-TIPCOB",
            "name": "Tipo de cobertura",
            "value_id": "MLA50541-TIPCOB-CUBIERTA",
            "value_name": "Cubierta",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        },
        {
            "id": "MLA50541-TIPOCOCH",
            "name": "Tipo de cochera",
            "value_id": "MLA50541-TIPOCOCH-FIJA",
            "value_name": "Fija",
            "attribute_group_id": "FIND",
            "attribute_group_name": "Ficha técnica"
        }
    ],
    "listing_source": "",
    "variations": [],
    "status": "active",
    "sub_status": [],
    "tags": [],
    "warranty": null,
    "catalog_product_id": null,
    "seller_custom_field": null,
    "parent_item_id": null,
    "differential_pricing": null,
    "deal_ids": [],
    "automatic_relist": false,
    "date_created": "2015-06-09T20:25:50.000Z",
    "last_updated": "2015-06-10T12:20:32.418Z"
}

End Package

PUT https://api.mercadolibre.com/users/186704185/classifieds_promotion_packs/1047628?access_token=$ACCESS_TOKEN
BODY
{ “status”:”{finished}” }

Example:

curl -X PUT -H "Content-Type: application/json" -d'{
> "status":"finished"
> }' https://api.mercadolibre.com/users/186704185/classifieds_promotion_packs/1047628?access_token=$ACCESS_TOKEN

FAQ

Is it possible to make an upgrade without an upgrade package?
No, is not possible.
Does hiring a package generates a charge?
No, the charge is only generated when you hire a upgrade package.
I have an upgrade packages hires, why can’t I upgrade my item?
Upgrade packages are for specific listing types and they have counted quota. Make sure you’re making an upgrade for the listing type of your hired package and that you still have available cuotas.
Is it possible to hire more than an upgrade package?
Yes, you can have multiple upgrade packages, on contrary you can’t have multiple listing packages.
Is it possible for a client to see of which package belongs an upgrade?
No, it’s not.
If I make a downgrade, does the quota becomes available?
Yes, the quotas can be re-used when you end an upgrade or an upgraded item.
How long does an upgrade lasts?
Each upgrade shares the ending date of it’s package.
Next topic: Start listing properties.

Please rate this

Classified locations

To list a real state item or a service, you will have to determine the location, which includes state, city and in most cases neighborhood as well. To accomplish this, it’s better if you get familiar with the Classified Locations API.

Contents:

Location selection

You only need to send the leaf location ID when publishing a item. This means that sending only the Neighborhood ID is enough for our API to complete with the corresponding State and City IDs.
If the chosen city does not have any neighborhood, then you will only need to send the City ID. Sending either the Neighborhood ID or the City ID is mandatory. If you were to send nothing but a State ID, our API will not allow you to list the item (anyway you should never send a State ID since it will be automatically filled according to the Neighborhood ID or City ID provided).
This resource will allow you to browse the possible classified locations by country, state, city and neighborhood.
Browse all the countries
Example:

curl -X GET https://api.mercadolibre.com/classified_locations/countries

Response:

[
  {
    "id": "AR",
    "name": "Argentina",
    "locale": "es_AR",
    "currency_id": "ARS"
  },
  {
    "id": "BR",
    "name": "Brasil",
    "locale": "pt_BR",
    "currency_id": "BRL"
  },
  {
    "id": "CO",
    "name": "Colombia",
    "locale": "es_CO",
    "currency_id": "COP"
  },
  {
    "id": "CR",
    "name": "Costa Rica",
    "locale": "es_CR",
    "currency_id": "CRC"
  },
  {
    "id": "CL",
    "name": "Chile",
    "locale": "es_CL",
    "currency_id": "CLP"
  },
  {
    "id": "EC",
    "name": "Ecuador",
    "locale": "es_EC",
    "currency_id": "USD"
  },
  {
    "id": "MX",
    "name": "Mexico",
    "locale": "es_MX",
    "currency_id": "MXN"
  },
  {
    "id": "PA",
    "name": "Panamá",
    "locale": "es_PA",
    "currency_id": "USD"
  },
  {
    "id": "PE",
    "name": "Peru",
    "locale": "es_PE",
    "currency_id": "PEN"
  },
  {
    "id": "PT",
    "name": "Portugal",
    "locale": "pt_PT",
    "currency_id": "EUR"
  },
  {
    "id": "DO",
    "name": "República Dominicana",
    "locale": "es_DO",
    "currency_id": "DOP"
  },
  {
    "id": "UY",
    "name": "Uruguay",
    "locale": "es_UY",
    "currency_id": "UYU"
  },
  {
    "id": "VE",
    "name": "Venezuela",
    "locale": "es_VE",
    "currency_id": "VEF"
  }
]


Browse country information

Resource:

https://api.mercadolibre.com/classified_locations/countries/{Country_Id}

Example:

curl -X GET https://api.mercadolibre.com/classified_locations/countries/AR

Response:

{
  "id": "AR",
  "name": "Argentina",
  "locale": "es_AR",
  "currency_id": "ARS",
  "decimal_separator": ",",
  "thousands_separator": ".",
  "time_zone": "GMT-03:00",
  "geo_information": {
    "location": {
      "latitude": -38.416097,
      "longitude": -63.616672
    }
  },
  "states": [
    {
      "id": "TUxBUEJSQWwyMzA1",
      "name": "Brasil"
    },
    {
      "id": "TUxBUENPU2ExMmFkMw",
      "name": "Bs.As. Costa Atlántica"
    },
    {
      "id": "TUxBUEdSQWU4ZDkz",
      "name": "Bs.As. G.B.A. Norte"
    },
    {
      "id": "TUxBUEdSQWVmNTVm",
      "name": "Bs.As. G.B.A. Oeste"
    },
    {
      "id": "TUxBUEdSQXJlMDNm",
      "name": "Bs.As. G.B.A. Sur"
    },
    {
      "id": "TUxBUFpPTmFpbnRl",
      "name": "Buenos Aires Interior"
    },
    {
      "id": "TUxBUENBUGw3M2E1",
      "name": "Capital Federal"
    },
    {
      "id": "TUxBUENBVGFiY2Fm",
      "name": "Catamarca"
    },
    {
      "id": "TUxBUENIQW8xMTNhOA",
      "name": "Chaco"
    },
    {
      "id": "TUxBUENIVXQxNDM1MQ",
      "name": "Chubut"
    },
    {
      "id": "TUxBUENPUnM5MjI0",
      "name": "Corrientes"
    },
    {
      "id": "TUxBUENPUmFkZGIw",
      "name": "Córdoba"
    },
    {
      "id": "TUxBUEVOVHMzNTdm",
      "name": "Entre Ríos"
    },
    {
      "id": "TUxBUEZPUmE1OTk5",
      "name": "Formosa"
    },
    {
      "id": "TUxBUEpVSnk3YmUz",
      "name": "Jujuy"
    },
    {
      "id": "TUxBUExBWmE1OWMy",
      "name": "La Pampa"
    },
    {
      "id": "TUxBUExBWmEyNzY0",
      "name": "La Rioja"
    },
    {
      "id": "TUxBUE1FTmE5OWQ4",
      "name": "Mendoza"
    },
    {
      "id": "TUxBUE1JU3MzNjIx",
      "name": "Misiones"
    },
    {
      "id": "TUxBUE5FVW4xMzMzNQ",
      "name": "Neuquén"
    },
    {
      "id": "TUxBUFJFUDQyMjQ4Ng",
      "name": "República Dominicana"
    },
    {
      "id": "TUxBUFLNT29iZmZm",
      "name": "Río Negro"
    },
    {
      "id": "TUxBUFNBTGFjMTJi",
      "name": "Salta"
    },
    {
      "id": "TUxBUFNBTm5lYjU4",
      "name": "San Juan"
    },
    {
      "id": "TUxBUFNBTnM0ZTcz",
      "name": "San Luis"
    },
    {
      "id": "TUxBUFNBTno3ZmY5",
      "name": "Santa Cruz"
    },
    {
      "id": "TUxBUFNBTmU5Nzk2",
      "name": "Santa Fe"
    },
    {
      "id": "TUxBUFNBTm9lOTlk",
      "name": "Santiago del Estero"
    },
    {
      "id": "TUxBUFRJRVoxM2M5YQ",
      "name": "Tierra del Fuego"
    },
    {
      "id": "TUxBUFRVQ244NmM3",
      "name": "Tucumán"
    },
    {
      "id": "TUxBUFVTQWl1cXdlMg",
      "name": "USA"
    },
    {
      "id": "TUxBUFVSVXllZDVl",
      "name": "Uruguay"
    }
  ]
}


Browse states

Resource:

https://api.mercadolibre.com/classified_locations/cities/{State_id}

Example:

curl -X GET  https://api.mercadolibre.com/classified_locations/states/TUxBUENBUGw3M2E1

Response:

{
  "id": "TUxBUENBUGw3M2E1",
  "name": "Capital Federal",
  "country": {
    "id": "AR",
    "name": "Argentina"
  },
  "geo_information": {
    "location": {
      "latitude": -34.6143048,
      "longitude": -58.4401655
    }
  },
  "cities": [
    {
      "id": "TUxBQ0NBUGZlZG1sYQ",
      "name": "Capital Federal"
    }
  ]
}

Browse city information

Resource:

https://api.mercadolibre.com/classified_locations/cities/{City_id}

Example:

curl -X GET https://api.mercadolibre.com/classified_locations/cities/TUxBQ0NBUGZlZG1sYQ

Response:

{
  "id": "TUxBQ0NBUGZlZG1sYQ",
  "name": "Capital Federal",
  "state": {
    "id": "TUxBUENBUGw3M2E1",
    "name": "Capital Federal"
  },
  "country": {
    "id": "AR",
    "name": "Argentina"
  },
  "geo_information": {
    "location": {
      "latitude": -34.6084175,
      "longitude": -58.3731613
    }
  },
  "neighborhoods": [
    {
      "id": "TUxBQkFHUjk3NjJa",
      "name": "Agronomía"
    },
    {
      "id": "TUxBQkFMTTMwNTBa",
      "name": "Almagro"
    },
    {
      "id": "TUxBQkJBTDMxMDZa",
      "name": "Balvanera"
    },
    {
      "id": "TUxBQkJBUjM0MDha",
      "name": "Barracas"
    },
    {
      "id": "TUxBQkJBUjQwMDQ3MA",
      "name": "Barrio Norte"
    },
    {
      "id": "TUxBQkJFTDcyNTJa",
      "name": "Belgrano"
    },
    {
      "id": "TUxBQkJFTDkwNjNa",
      "name": "Belgrano Barrancas"
    },
    {
      "id": "TUxBQkJFTDk4MDRa",
      "name": "Belgrano C"
    },
    {
      "id": "TUxBQkJFTDU0ODda",
      "name": "Belgrano Chico"
    },
    {
      "id": "TUxBQkJFTDU5NzNa",
      "name": "Belgrano R"
    },
    {
      "id": "TUxBQkJPRTQ0OTRa",
      "name": "Boedo"
    },
    {
      "id": "TUxBQkJPVDQ2NTFa",
      "name": "Botánico"
    },
    {
      "id": "TUxBQkNBQjM4MDda",
      "name": "Caballito"
    },
    {
      "id": "TUxBQkNIQTM5NjBa",
      "name": "Chacarita"
    },
    {
      "id": "TUxBQkNPRzY5MTZa",
      "name": "Coghlan"
    },
    {
      "id": "TUxBQkNPTDI3NDNa",
      "name": "Colegiales"
    },
    {
      "id": "TUxBQkNPTjgyODY1Mg",
      "name": "Congreso"
    },
    {
      "id": "TUxBQkNPTjExMDBa",
      "name": "Constitución"
    },
    {
      "id": "TUxBQkZMTzMwNzRa",
      "name": "Flores"
    },
    {
      "id": "TUxBQkZMTzg5MjFa",
      "name": "Floresta"
    },
    {
      "id": "TUxBQkxBQjk1ODJa",
      "name": "La Boca"
    },
    {
      "id": "TUxBQkxBUzIxNTJa",
      "name": "Las Cañitas"
    },
    {
      "id": "TUxBQkxJTjEzNTha",
      "name": "Liniers"
    },
    {
      "id": "TUxBQk1BVDMwMDJa",
      "name": "Mataderos"
    },
    {
      "id": "TUxBQk1PTjUxOTJa",
      "name": "Monserrat"
    },
    {
      "id": "TUxBQk1PTjE2OTBa",
      "name": "Monte Castro"
    },
    {
      "id": "TUxBQk5VRTc3MTZa",
      "name": "Nueva Pompeya"
    },
    {
      "id": "TUxBQk7a0TcwOTRa",
      "name": "Núñez"
    },
    {
      "id": "TUxBQk9OQzM1Mjk5Ng",
      "name": "Once"
    },
    {
      "id": "TUxBQlBBTDI1MTVa",
      "name": "Palermo"
    },
    {
      "id": "TUxBQlBBTDg3OTha",
      "name": "Palermo Chico"
    },
    {
      "id": "TUxBQlBBTDg1NjJa",
      "name": "Palermo Hollywood"
    },
    {
      "id": "TUxBQlBBTDgwMjla",
      "name": "Palermo Nuevo"
    },
    {
      "id": "TUxBQlBBTDg3MDda",
      "name": "Palermo Soho"
    },
    {
      "id": "TUxBQlBBTDE5ODla",
      "name": "Palermo Viejo"
    },
    {
      "id": "TUxBQlBBUjQ1NDda",
      "name": "Parque Avellaneda"
    },
    {
      "id": "TUxBQlBBUjUyOTZa",
      "name": "Parque Chacabuco"
    },
    {
      "id": "TUxBQlBBUjYwMzZa",
      "name": "Parque Patricios"
    },
    {
      "id": "TUxBQlBBVDI0ODFa",
      "name": "Paternal"
    },
    {
      "id": "TUxBQlBVRTQ5NjBa",
      "name": "Puerto Madero"
    },
    {
      "id": "TUxBQlJFQzkyMTVa",
      "name": "Recoleta"
    },
    {
      "id": "TUxBQlJFVDgyMDVa",
      "name": "Retiro"
    },
    {
      "id": "TUxBQlNBQTM3Mzda",
      "name": "Saavedra"
    },
    {
      "id": "TUxBQlNBTjkwNTZa",
      "name": "San Cristóbal"
    },
    {
      "id": "TUxBQlNBTjgzMjRa",
      "name": "San Nicolás"
    },
    {
      "id": "TUxBQlNBTjgxMzNa",
      "name": "San Telmo"
    },
    {
      "id": "TUxBQlNBTjEyMjNa",
      "name": "Santa Rita"
    },
    {
      "id": "TUxBQlZFTDIwNDha",
      "name": "Velez Sarsfield"
    },
    {
      "id": "TUxBQlZFUjY3MDFa",
      "name": "Versailles"
    },
    {
      "id": "TUxBQlZJTDQyMjBa",
      "name": "Villa Crespo"
    },
    {
      "id": "TUxBQlZJTDYzNzZa",
      "name": "Villa Devoto"
    },
    {
      "id": "TUxBQlZJTDI1ODla",
      "name": "Villa Gral. Mitre"
    },
    {
      "id": "TUxBQlZJTDQ4MzBa",
      "name": "Villa Lugano"
    },
    {
      "id": "TUxBQlZJTDI3MDJa",
      "name": "Villa Luro"
    },
    {
      "id": "TUxBQlZJTDQyMjFa",
      "name": "Villa Ortúzar"
    },
    {
      "id": "TUxBQlZJTDE2MDBa",
      "name": "Villa Pueyrredón"
    },
    {
      "id": "TUxBQlZJTDM3Mzda",
      "name": "Villa Real"
    },
    {
      "id": "TUxBQlZJTDU5MTFa",
      "name": "Villa Riachuelo"
    },
    {
      "id": "TUxBQlZJTDM5MjZa",
      "name": "Villa Soldati"
    },
    {
      "id": "TUxBQlZJTDcwOTla",
      "name": "Villa Urquiza"
    },
    {
      "id": "TUxBQlZJTDc4MDda",
      "name": "Villa del Parque"
    }
  ]
}


Browse neighborhoods

Resource:

https://api.mercadolibre.com/classified_locations/neighborhoods/{Neighborhood_Id}

Example:

curl -X GET https://api.mercadolibre.com/classified_locations/neighborhoods/TUxBQkNBQjM4MDda

Response:

{
  "id": "TUxBQkNBQjM4MDda",
  "name": "Caballito",
  "city": {
    "id": "TUxBQ0NBUGZlZG1sYQ",
    "name": "Capital Federal"
  },
  "state": {
    "id": "TUxBUENBUGw3M2E1",
    "name": "Capital Federal"
  },
  "country": {
    "id": "AR",
    "name": "Argentina"
  },
  "geo_information": {
    "location": {
      "latitude": -34.6166667,
      "longitude": -58.45
    }
  },
  "subneighborhoods": [
  ]
}


Search a real estate item by location

Once you’ve selected a location for you real state item, this resource will allow you to search items by it’s location in between a specified latitude and longitud range.
Resource:

https://api.mercadolibre.com/sites/MLA/search?item_location=lat:{latitude1_latitude2},lon:{longitude1_longitude2}&category={Category_Id}



Example:
I’m including the real state items category on MLA, a location range inside Buenos Aires, AR and a limit of 2 items in the results.

curl -X GET https://api.mercadolibre.com/sites/MLA/search?item_location=lat:-37.987148_-30.987148,lon:-57.5483864_-50.5483864&category=MLA1459&limit=2

Response:

{
  "site_id": "MLA",
  "paging": {
    "total": 6246,
    "offset": 0,
    "limit": 2
  },
  "results": [
    {
      "id": "MLA532174177",
      "site_id": "MLA",
      "title": "Casa En Valeria Del Mar (gustavo)",
      "subtitle": null,
      "seller": {
        "id": 156627013,
        "power_seller_status": null,
        "car_dealer": false,
        "real_estate_agency": false
      },
      "price": 750,
      "currency_id": "ARS",
      "available_quantity": 1,
      "sold_quantity": 0,
      "buying_mode": "classified",
      "listing_type_id": "gold_premium",
      "stop_time": "2015-11-11T16:16:52.000Z",
      "condition": "new",
      "permalink": "http://casa.mercadolibre.com.ar/MLA-532174177-casa-en-valeria-del-mar-gustavo-_JM",
      "thumbnail": "http://mla-s2-p.mlstatic.com/19874-MLA20179087101_102014-I.jpg",
      "accepts_mercadopago": false,
      "installments": null,
      "address": {
        "state_id": "TUxBUENPU2ExMmFkMw",
        "state_name": "Bs.as. Costa Atlántica",
        "city_id": "TUxBQ1ZBTDM4MGFj",
        "city_name": "Valeria del Mar",
        "area_code": "02267",
        "phone1": "15538544"
      },
      "shipping": {
        "free_shipping": false,
        "mode": "not_specified"
      },
      "seller_address": {
        "id": 139563091,
        "comment": "",
        "address_line": "urthubey 1181",
        "zip_code": "7167",
        "country": {
          "id": "AR",
          "name": "Argentina"
        },
        "state": {
          "id": "AR-B",
          "name": "Buenos Aires"
        },
        "city": {
          "id": "TUxBQ1ZBTDM4MGFj",
          "name": "Valeria del Mar"
        },
        "latitude": "",
        "longitude": ""
      },
      "seller_contact": {
        "contact": "",
        "other_info": "",
        "area_code": "02267",
        "phone": "15538544",
        "area_code2": "",
        "phone2": "",
        "email": "",
        "webpage": ""
      },
      "location": {
        "address_line": "urthubey 1100",
        "zip_code": "",
        "subneighborhood": null,
        "neighborhood": {
          "id": "",
          "name": ""
        },
        "city": {
          "id": "TUxBQ1ZBTDM4MGFj",
          "name": "Valeria del Mar"
        },
        "state": {
          "id": "TUxBUENPU2ExMmFkMw",
          "name": "Bs.as. Costa Atlántica"
        },
        "country": {
          "id": "AR",
          "name": "Argentina"
        },
        "latitude": -37.137337,
        "longitude": -56.89233
      },
      "attributes": [
        {
          "attribute_group_id": "FIND",
          "id": "MLA1459-INMUEBLE",
          "name": "Inmueble",
          "value_name": "Casa",
          "value_id": "MLA1459-INMUEBLE-CASA",
          "attribute_group_name": "Ficha técnica"
        },
        {
          "attribute_group_id": "FIND",
          "id": "MLA1459-OPERACION",
          "name": "Operación",
          "value_name": "Alquiler Temporario",
          "value_id": "MLA1459-OPERACION-ALQUILER_DE_TEMPORADA",
          "attribute_group_name": "Ficha técnica"
        },
        {
          "attribute_group_id": "FIND",
          "id": "MLA1466-AMBQTY",
          "name": "Ambientes",
          "value_name": "4",
          "value_id": "MLA1466-AMBQTY-4",
          "attribute_group_name": "Ficha tecnica"
        },
        {
          "attribute_group_id": "FIND",
          "id": "MLA1466-MTRS",
          "name": "Superficie cubierta (m²)",
          "value_name": "90",
          "value_id": "",
          "attribute_group_name": "Ficha técnica"
        }
      ],
      "original_price": null,
      "category_id": "MLA50278"
    },
    {
      "id": "MLA532037889",
      "site_id": "MLA",
      "title": "Alquilo Duplex 3 Amb Barrio San Rafael - Mar De Ajo",
      "subtitle": null,
      "seller": {
        "id": 62970704,
        "power_seller_status": null,
        "car_dealer": false,
        "real_estate_agency": false
      },
      "price": 400,
      "currency_id": "ARS",
      "available_quantity": 1,
      "sold_quantity": 0,
      "buying_mode": "classified",
      "listing_type_id": "gold_premium",
      "stop_time": "2015-11-11T15:49:46.000Z",
      "condition": "used",
      "permalink": "http://casa.mercadolibre.com.ar/MLA-532037889-alquilo-duplex-3-amb-barrio-san-rafael-mar-de-ajo-_JM",
      "thumbnail": "http://mla-s2-p.mlstatic.com/20590-MLA20193199450_112014-I.jpg",
      "accepts_mercadopago": false,
      "installments": null,
      "address": {
        "state_id": "TUxBUENPU2ExMmFkMw",
        "state_name": "Bs.as. Costa Atlántica",
        "city_id": "TUxBQ01BUjNmZDhl",
        "city_name": "Mar de Ajo",
        "area_code": "011",
        "phone1": "15-5919-9616"
      },
      "shipping": {
        "free_shipping": false,
        "mode": "not_specified"
      },
      "seller_address": {
        "id": 152837111,
        "comment": "Duplex 4",
        "address_line": "Daniel Rial 200",
        "zip_code": "7109",
        "country": {
          "id": "AR",
          "name": "Argentina"
        },
        "state": {
          "id": "AR-B",
          "name": "Buenos Aires"
        },
        "city": {
          "id": "TUxBQ01BUjNmZDhl",
          "name": "Mar de Ajo"
        },
        "latitude": -36.715473,
        "longitude": -56.676258
      },
      "seller_contact": {
        "contact": "",
        "other_info": "",
        "area_code": "011",
        "phone": "15-5919-9616",
        "area_code2": "",
        "phone2": "",
        "email": "",
        "webpage": ""
      },
      "location": {
        "address_line": "Daniel Rial 200",
        "zip_code": "",
        "subneighborhood": null,
        "neighborhood": {
          "id": "",
          "name": ""
        },
        "city": {
          "id": "TUxBQ01BUjNmZDhl",
          "name": "Mar de Ajo"
        },
        "state": {
          "id": "TUxBUENPU2ExMmFkMw",
          "name": "Bs.as. Costa Atlántica"
        },
        "country": {
          "id": "AR",
          "name": "Argentina"
        },
        "latitude": -36.715473,
        "longitude": -56.676258
      },
      "attributes": [
        {
          "attribute_group_id": "FIND",
          "id": "MLA1459-INMUEBLE",
          "name": "Inmueble",
          "value_name": "Casa",
          "value_id": "MLA1459-INMUEBLE-CASA",
          "attribute_group_name": "Ficha técnica"
        },
        {
          "attribute_group_id": "FIND",
          "id": "MLA1459-OPERACION",
          "name": "Operación",
          "value_name": "Alquiler Temporario",
          "value_id": "MLA1459-OPERACION-ALQUILER_DE_TEMPORADA",
          "attribute_group_name": "Ficha técnica"
        },
        {
          "attribute_group_id": "FIND",
          "id": "MLA1466-AMBQTY",
          "name": "Ambientes",
          "value_name": "3",
          "value_id": "MLA1466-AMBQTY-3",
          "attribute_group_name": "Ficha tecnica"
        },
        {
          "attribute_group_id": "FIND",
          "id": "MLA1466-MTRS",
          "name": "Superficie cubierta (m²)",
          "value_name": "95",
          "value_id": "",
          "attribute_group_name": "Ficha técnica"
        }
      ],
      "original_price": null,
      "category_id": "MLA50278"
    }
  ],
  "secondary_results": [
  ],
  "related_results": [
  ],
  "sort": {
    "id": "relevance",
    "name": "More relevant"
  },
  "available_sorts": [
    {
      "id": "price_asc",
      "name": "Lower price"
    },
    {
      "id": "price_desc",
      "name": "Higher price"
    }
  ],
  "filters": [
    {
      "id": "category",
      "name": "Categories",
      "type": "text",
      "values": [
        {
          "id": "MLA1459",
          "name": "Inmuebles",
          "path_from_root": [
            {
              "id": "MLA1459",
              "name": "Inmuebles"
            }
          ]
        }
      ]
    }
  ],
  "available_filters": [
    {
      "id": "9991459-AMLA_1459_1",
      "name": "Inmueble",
      "type": "text",
      "values": [
        {
          "id": "9991459-AMLA_1459_1-MMLA12617",
          "name": "Departamentos",
          "results": 2624
        },
        {
          "id": "9991459-AMLA_1459_1-MMLA12616",
          "name": "Casas",
          "results": 2597
        },
        {
          "id": "9991459-AMLA_1459_1-MMLA12619",
          "name": "Terrenos y Lotes",
          "results": 263
        },
        {
          "id": "9991459-AMLA_1459_1-MMLA12777",
          "name": "Tiempo Compartido",
          "results": 184
        },
        {
          "id": "9991459-AMLA_1459_1-MMLA32199",
          "name": "PH",
          "results": 82
        },
        {
          "id": "9991459-AMLA_1459_1-MMLA23362",
          "name": "Locales",
          "results": 45
        },
        {
          "id": "9991459-AMLA_1459_1-MMLA12780",
          "name": "Fondo de Comercio",
          "results": 17
        },
        {
          "id": "9991459-AMLA_1459_1-MMLA12778",
          "name": "Cocheras",
          "results": 10
        },
        {
          "id": "9991459-AMLA_1459_1-MMLA12781",
          "name": "Quintas",
          "results": 8
        },
        {
          "id": "9991459-AMLA_1459_1-MMLA12782",
          "name": "Oficinas y Consultorios",
          "results": 4
        },
        {
          "id": "9991459-AMLA_1459_1-MMLA12615",
          "name": "Campos",
          "results": 3
        },
        {
          "id": "9991459-AMLA_1459_1-MMLA28331",
          "name": "Depósitos y Galpones",
          "results": 2
        },
        {
          "id": "9991459-AMLA_1459_1-MMLA12618",
          "name": "Otros Inmuebles",
          "results": 407
        }
      ]
    },
    {
      "id": "9991459-AMLA_1459_2",
      "name": "Operación",
      "type": "text",
      "values": [
        {
          "id": "9991459-AMLA_1459_2-MMLA14069",
          "name": "Alquiler Temporario",
          "results": 4794
        },
        {
          "id": "9991459-AMLA_1459_2-MMLA12623",
          "name": "Venta",
          "results": 1199
        },
        {
          "id": "9991459-AMLA_1459_2-MMLA12620",
          "name": "Alquiler",
          "results": 253
        }
      ]
    },
    {
      "id": "state",
      "name": "Location",
      "type": "text",
      "values": [
        {
          "id": "TUxBUENPU2ExMmFkMw",
          "name": "Bs.As. Costa Atlántica",
          "results": 5666
        },
        {
          "id": "TUxBUFVSVXllZDVl",
          "name": "Uruguay",
          "results": 566
        },
        {
          "id": "TUxBUFpPTmFpbnRl",
          "name": "Buenos Aires Interior",
          "results": 14
        }
      ]
    },
    {
      "id": "price",
      "name": "Price range",
      "type": "range",
      "values": [
        {
          "id": "*-700.0",
          "name": "Up to $700",
          "results": 2043
        },
        {
          "id": "700.0-8000.0",
          "name": "$700 to $8.000",
          "results": 2013
        },
        {
          "id": "8000.0-*",
          "name": "More than $8.000",
          "results": 2190
        }
      ]
    },
    {
      "id": "159-MTRSTOTAL",
      "name": "Metros totales",
      "type": "range",
      "values": [
        {
          "id": "*-35.0",
          "name": "Up to 35 m²",
          "results": 1078
        },
        {
          "id": "35.0-65.0",
          "name": "35 to 65m²",
          "results": 1397
        },
        {
          "id": "65.0-100.0",
          "name": "65 to 100m²",
          "results": 1065
        },
        {
          "id": "100.0-300.0",
          "name": "100 to 300m²",
          "results": 1285
        },
        {
          "id": "300.0-*",
          "name": "More than 300m²",
          "results": 1421
        }
      ]
    },
    {
      "id": "159-AMBQTY",
      "name": "Cant. de ambientes",
      "type": "text",
      "values": [
        {
          "id": "159-AMBQTY-1",
          "name": "1 ambiente",
          "results": 381
        },
        {
          "id": "159-AMBQTY-2",
          "name": "2 ambientes",
          "results": 1425
        },
        {
          "id": "159-AMBQTY-3",
          "name": "3 ambientes",
          "results": 1820
        },
        {
          "id": "159-AMBQTY-4",
          "name": "4 ambientes",
          "results": 859
        }
      ]
    },
    {
      "id": "159-GARAGE",
      "name": "Cochera/s",
      "type": "text",
      "values": [
        {
          "id": "159-GARAGE-1",
          "name": "1 cochera",
          "results": 2250
        },
        {
          "id": "159-GARAGE-2",
          "name": "2 cocheras",
          "results": 351
        },
        {
          "id": "159-GARAGE-3",
          "name": "3 cocheras",
          "results": 74
        },
        {
          "id": "159-GARAGE-4_O_MAS",
          "name": "4 o más cocheras",
          "results": 150
        }
      ]
    },
    {
      "id": "159-AIRCEN",
      "name": "Aire acondicionado central",
      "type": "boolean",
      "values": [
        {
          "id": "159-AIRCEN-YES",
          "name": "Con aire acondicionado central",
          "results": 517
        }
      ]
    },
    {
      "id": "159-ALAR",
      "name": "Alarma",
      "type": "boolean",
      "values": [
        {
          "id": "159-ALAR-YES",
          "name": "Con Alarma",
          "results": 774
        }
      ]
    },
    {
      "id": "real_estate_agency",
      "name": "Real estate agency filter",
      "type": "boolean",
      "values": [
        {
          "id": "yes",
          "name": "Real estate agency",
          "results": 910
        }
      ]
    },
    {
      "id": "condition",
      "name": "Condition filter",
      "type": "text",
      "values": [
        {
          "id": "new",
          "name": "New",
          "results": 795
        },
        {
          "id": "used",
          "name": "Used",
          "results": 5124
        }
      ]
    },
    {
      "id": "power_seller",
      "name": "Seller quality filter",
      "type": "boolean",
      "values": [
        {
          "id": "yes",
          "name": "Best sellers",
          "results": 23
        }
      ]
    },
    {
      "id": "buying_mode",
      "name": "Buying mode filter",
      "type": "text",
      "values": [
        {
          "id": "buy_it_now",
          "name": "Buy it now",
          "results": 6246
        }
      ]
    },
    {
      "id": "since",
      "name": "Auction start date filter",
      "type": "text",
      "values": [
        {
          "id": "today",
          "name": "Starting today",
          "results": 117
        }
      ]
    },
    {
      "id": "until",
      "name": "Auction stop filter",
      "type": "text",
      "values": [
        {
          "id": "today",
          "name": "Ending today",
          "results": 22
        }
      ]
    },
    {
      "id": "has_video",
      "name": "Video publications filter",
      "type": "boolean",
      "values": [
        {
          "id": "yes",
          "name": "Publications with video",
          "results": 200
        }
      ]
    },
    {
      "id": "has_pictures",
      "name": "Items with images filter",
      "type": "boolean",
      "values": [
        {
          "id": "yes",
          "name": "With pictures",
          "results": 6177
        }
      ]
    }
  ]
}


Next topic: Manage packages

Please rate this

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.

Contents:

Categories by Site

The Sites resource can give you the category structure for a particular country, in this case Argentina.

https://api.mercadolibre.com/sites/MLA/categories
{
    "id": "MLA5725",
    "name": "Accesorios para Vehículos"
  },
  {
    "id": "MLA1071",
    "name": "Animales y Mascotas"
  },
  {
    "id": "MLA1367",
    "name": "Antigüedades"
  },
  {
    "id": "MLA1368",
    "name": "Arte y Artesanías"
  },
  {
    "id": "MLA1743",
    "name": "Autos, Motos y Otros"
  },
  {
    "id": "MLA1384",
    "name": "Bebés"
  },
  {
    "id": "MLA1051",
    "name": "Celulares y Teléfonos"
  },
  {
    "id": "MLA1798",
    "name": "Coleccionables y Hobbies"
  },
  {
    "id": "MLA1648",
    "name": "Computación"
  },
  {
    "id": "MLA1144",
    "name": "Consolas y Videojuegos"
  },
  {
    "id": "MLA1039",
    "name": "Cámaras y Accesorios"
  },
  {
    "id": "MLA1403",
    "name": "Delicatessen y Vinos"
  },
  {
    "id": "MLA1276",
    "name": "Deportes y Fitness"
  },
  {
    "id": "MLA5726",
    "name": "Electrodomésticos y Aires Ac."
  },
  {
    "id": "MLA1000",
    "name": "Electrónica, Audio y Video"
  },
  {
    "id": "MLA2547",
    "name": "Entradas para Eventos"
  },
  {
    "id": "MLA1574",
    "name": "Hogar, Muebles y Jardín"
  },
  {
    "id": "MLA1499",
    "name": "Industrias y Oficinas"
  },
  {
    "id": "MLA1459",
    "name": "Inmuebles"
  }

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:

https://api.mercadolibre.com/categories/MLA1459
{
  "id": "MLA1459",
  "name": "Inmuebles",
  "picture": "http://resources.mlstatic.com/category/images/cc0eed64-9cfb-4b78-9258-6266475f6427.png",
  "permalink": "http://www.mercadolibre.com.ar/inmuebles/",
  "total_items_in_this_category": 109788,
  "path_from_root": [
    {
      "id": "MLA1459",
      "name": "Inmuebles"
    }
  ],
  "children_categories": [
    {
      "id": "MLA374730",
      "name": "Camas Náuticas",
      "total_items_in_this_category": 56
    },
    {
      "id": "MLA1496",
      "name": "Campos",
      "total_items_in_this_category": 747
    },
    {
      "id": "MLA1466",
      "name": "Casas",
      "total_items_in_this_category": 29579
    },
    {
      "id": "MLA50541",
      "name": "Cocheras",
      "total_items_in_this_category": 1659
    },
    {
      "id": "MLA1472",
      "name": "Departamentos",
      "total_items_in_this_category": 43732
    },
    {
      "id": "MLA1475",
      "name": "Depósitos y Galpones",
      "total_items_in_this_category": 1474
    },
    {
      "id": "MLA50545",
      "name": "Fondo de Comercio",
      "total_items_in_this_category": 1925
    },
    {
      "id": "MLA79242",
      "name": "Locales",
      "total_items_in_this_category": 2533
    },
    {
      "id": "MLA50538",
      "name": "Oficinas y Consultorios",
      "total_items_in_this_category": 2711
    },
    {
      "id": "MLA1892",
      "name": "Otros Inmuebles",
      "total_items_in_this_category": 2236
    },
    {
      "id": "MLA105179",
      "name": "PH",
      "total_items_in_this_category": 3066
    },
    {
      "id": "MLA50544",
      "name": "Parcelas, Nichos y Bóvedas",
      "total_items_in_this_category": 230
    },
    {
      "id": "MLA50547",
      "name": "Quintas",
      "total_items_in_this_category": 1828
    },
    {
      "id": "MLA1493",
      "name": "Terrenos y Lotes",
      "total_items_in_this_category": 17463
    },
    {
      "id": "MLA50536",
      "name": "Tiempo Compartido",
      "total_items_in_this_category": 566
    }
  ],
  "attribute_types": "attributes",
  "settings": {
    "adult_content": false,
    "buying_allowed": false,
    "buying_modes": [
      "classified"
    ],
    "coverage_areas": "not_allowed",
    "currencies": [
      "ARS",
      "USD"
    ],
    "fragile": false,
    "immediate_payment": "optional",
    "item_conditions": [
      "new",
      "not_specified",
      "used"
    ],
    "items_reviews_allowed": false,
    "max_description_length": 50000,
    "max_pictures_per_item": 15,
    "max_sub_title_length": 70,
    "max_title_length": 200,
    "price": "required",
    "restrictions": [
    ],
    "rounded_address": true,
    "seller_contact": "optional",
    "shipping_modes": [
      "custom",
      "not_specified"
    ],
    "shipping_options": [
    ],
    "shipping_profile": "not_allowed",
    "show_contact_information": true,
    "simple_shipping": "not_allowed",
    "stock": "required",
    "tags": [
    ],
    "vip_subdomain": "inmueble",
    "mirror_category": null,
    "listing_allowed": false,
    "maximum_price": null,
    "minimum_price": null
  },
  "meta_categ_id": null,
  "attributable": true
}

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:

https://api.mercadolibre.com/categories/MLA79242

Response:

{
  "id": "MLA79242",
  "name": "Locales",
  "picture": "http://resources.mlstatic.com/category/images/f1f2bbe1-b5d4-45b1-9b9c-ac142b6bc64f.png",
  "permalink": null,
  "total_items_in_this_category": 2533,
  "path_from_root": [
    {
      "id": "MLA1459",
      "name": "Inmuebles"
    },
    {
      "id": "MLA79242",
      "name": "Locales"
    }
  ],
  "children_categories": [
    {
      "id": "MLA79243",
      "name": "Alquiler",
      "total_items_in_this_category": 1332
    },
    {
      "id": "MLA79244",
      "name": "Venta",
      "total_items_in_this_category": 1197
    }
  ],
  "attribute_types": "attributes",
  "settings": {
    "adult_content": false,
    "buying_allowed": false,
    "buying_modes": [
      "classified"
    ],
    "coverage_areas": "not_allowed",
    "currencies": [
      "ARS",
      "USD"
    ],
    "fragile": false,
    "immediate_payment": "optional",
    "item_conditions": [
      "not_specified",
      "used",
      "new"
    ],
    "items_reviews_allowed": false,
    "max_description_length": 50000,
    "max_pictures_per_item": 15,
    "max_sub_title_length": 70,
    "max_title_length": 200,
    "price": "required",
    "restrictions": [
    ],
    "rounded_address": true,
    "seller_contact": "optional",
    "shipping_modes": [
      "custom",
      "not_specified"
    ],
    "shipping_options": [
    ],
    "shipping_profile": "not_allowed",
    "show_contact_information": true,
    "simple_shipping": "not_allowed",
    "stock": "required",
    "tags": [
    ],
    "vip_subdomain": "inmueble",
    "mirror_category": null,
    "listing_allowed": false,
    "maximum_price": null,
    "minimum_price": null
  },
  "meta_categ_id": 23362,
  "attributable": false
}

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:

https://api.mercadolibre.com/categories/MLA79243

Response:

{
  "id": "MLA79243",
  "name": "Alquiler",
  "picture": null,
  "permalink": null,
  "total_items_in_this_category": 1332,
  "path_from_root": [
    {
      "id": "MLA1459",
      "name": "Inmuebles"
    },
    {
      "id": "MLA79242",
      "name": "Locales"
    },
    {
      "id": "MLA79243",
      "name": "Alquiler"
    }
  ],
  "children_categories": [
  ],
  "attribute_types": "attributes",
  "settings": {
    "adult_content": false,
    "buying_allowed": false,
    "buying_modes": [
      "classified"
    ],
    "coverage_areas": "not_allowed",
    "currencies": [
      "ARS",
      "USD"
    ],
    "fragile": false,
    "immediate_payment": "optional",
    "item_conditions": [
      "new",
      "not_specified",
      "used"
    ],
    "items_reviews_allowed": false,
    "max_description_length": 50000,
    "max_pictures_per_item": 15,
    "max_sub_title_length": 70,
    "max_title_length": 200,
    "price": "required",
    "restrictions": [
    ],
    "rounded_address": true,
    "seller_contact": "optional",
    "shipping_modes": [
      "not_specified",
      "custom"
    ],
    "shipping_options": [
    ],
    "shipping_profile": "not_allowed",
    "show_contact_information": true,
    "simple_shipping": "not_allowed",
    "stock": "required",
    "tags": [
    ],
    "vip_subdomain": "inmueble",
    "mirror_category": null,
    "listing_allowed": true,
    "maximum_price": 250000,
    "minimum_price": 100
  },
  "meta_categ_id": 12620,
  "attributable": false
}

Specific category attributes

To know the specific category attributes and possible values you need to send to list an item check the attributes resource:

Example:

https://api.mercadolibre.com/categories/MLA79243/attributes
{
    "id": "MLA1459-INMUEBLE",
    "name": "Inmueble",
    "value_type": "list",
    "tags": {
      "fixed": true,
      "required": true
    },
    "values": [
      {
        "id": "MLA1459-INMUEBLE-LOCALES",
        "name": "Locales"
      }
    ],
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "MLA1459-OPERACION",
    "name": "Operación",
    "value_type": "list",
    "tags": {
      "fixed": true,
      "required": true
    },
    "values": [
      {
        "id": "MLA1459-OPERACION-ALQUILER",
        "name": "Alquiler"
      }
    ],
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "MLA79242-ANTIG",
    "name": "Antigüedad",
    "value_type": "list",
    "tags": {
      "required": true
    },
    "values": [
      {
        "id": "MLA79242-ANTIG-A_ESTRENAR",
        "name": "A estrenar"
      },
      {
        "id": "MLA79242-ANTIG-MAX_5_ANOS",
        "name": "Max 5 años"
      },
      {
        "id": "MLA79242-ANTIG-MAX_10_ANOS",
        "name": "Max 10 años"
      },
      {
        "id": "MLA79242-ANTIG-MAX_20_ANOS",
        "name": "Max 20 años"
      },
      {
        "id": "MLA79242-ANTIG-MAX_30_ANOS",
        "name": "Max 30 años"
      },
      {
        "id": "MLA79242-ANTIG-MAX_40_ANOS",
        "name": "Max 40 años"
      },
      {
        "id": "MLA79242-ANTIG-MAS_DE_40_ANOS",
        "name": "Más de 40 años"
      }
    ],
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "MLA79242-BATHQTY",
    "name": "Baños",
    "value_type": "list",
    "tags": {
      "required": true
    },
    "values": [
      {
        "id": "MLA79242-BATHQTY-1",
        "name": "1"
      },
      {
        "id": "MLA79242-BATHQTY-2",
        "name": "2"
      },
      {
        "id": "MLA79242-BATHQTY-3",
        "name": "3"
      },
      {
        "id": "MLA79242-BATHQTY-4",
        "name": "4"
      },
      {
        "id": "MLA79242-BATHQTY-MAS_DE_4",
        "name": "Más de 4"
      }
    ],
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "MLA79242-ESTADO",
    "name": "Estado",
    "value_type": "list",
    "tags": {
      "required": true
    },
    "values": [
      {
        "id": "MLA79242-ESTADO-A_REFACCIONAR",
        "name": "A refaccionar"
      },
      {
        "id": "MLA79242-ESTADO-BUENO",
        "name": "Bueno"
      },
      {
        "id": "MLA79242-ESTADO-EXCELENTE",
        "name": "Excelente"
      },
      {
        "id": "MLA79242-ESTADO-MUY_BUENO",
        "name": "Muy bueno"
      },
      {
        "id": "MLA79242-ESTADO-REGULAR",
        "name": "Regular"
      }
    ],
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "MLA79242-SUPCONSCL",
    "name": "Superficie construida (m²)",
    "value_type": "number",
    "value_max_length": 60,
    "tags": {
      "required": true
    },
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "MLA79242-SUPTOTMX",
    "name": "Superficie total (m²)",
    "value_type": "number",
    "value_max_length": 60,
    "tags": {
      "required": true
    },
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "MLA1459-HORPREF",
    "name": "Horario de contacto",
    "value_type": "string",
    "value_max_length": 60,
    "tags": {
    },
    "attribute_group_id": "FIND",
    "attribute_group_name": "Ficha técnica"
  },
  {
    "id": "MLA79242-PISOSQTY",
    "name": "Plantas",
    "value_type": "list",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-PISOSQTY-1",
        "name": "1"
      },
      {
        "id": "MLA79242-PISOSQTY-2",
        "name": "2"
      },
      {
        "id": "MLA79242-PISOSQTY-3",
        "name": "3"
      },
      {
        "id": "MLA79242-PISOSQTY-MAS_DE_3",
        "name": "Más de 3"
      }
    ],
    "attribute_group_id": "ADICIONALES",
    "attribute_group_name": "Adicionales"
  },
  {
    "id": "MLA79242-LOCALI",
    "name": "Localización",
    "value_type": "list",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-LOCALI-A_LA_CALLE",
        "name": "A la calle"
      },
      {
        "id": "MLA79242-LOCALI-CENTRO_COMERCIAL",
        "name": "Centro comercial"
      },
      {
        "id": "MLA79242-LOCALI-GALERIA",
        "name": "Galería"
      },
      {
        "id": "MLA79242-LOCALI-SHOPPING",
        "name": "Shopping"
      },
      {
        "id": "MLA79242-LOCALI-OTRO_LUGAR",
        "name": "Otro lugar"
      }
    ],
    "attribute_group_id": "ADICIONALES",
    "attribute_group_name": "Adicionales"
  },
  {
    "id": "MLA79242-AGUACORR",
    "name": "Agua Corriente",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-AGUACORR-N",
        "name": "No"
      },
      {
        "id": "MLA79242-AGUACORR-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-AIRACON",
    "name": "Aire acondicionado",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-AIRACON-N",
        "name": "No"
      },
      {
        "id": "MLA79242-AIRACON-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-ALARSEG",
    "name": "Alarma de seguridad",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-ALARSEG-N",
        "name": "No"
      },
      {
        "id": "MLA79242-ALARSEG-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-ELEVATOR",
    "name": "Ascensor",
    "value_type": "list",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-ELEVATOR-SI",
        "name": "Sí"
      },
      {
        "id": "MLA79242-ELEVATOR-NO",
        "name": "No"
      }
    ],
    "attribute_group_id": "ADICIONALES",
    "attribute_group_name": "Adicionales"
  },
  {
    "id": "MLA79242-CALEF",
    "name": "Calefacción",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-CALEF-N",
        "name": "No"
      },
      {
        "id": "MLA79242-CALEF-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "GARAGE",
    "name": "Cocheras",
    "value_type": "list",
    "tags": {
    },
    "values": [
      {
        "id": "GARAGE-6a020b",
        "name": "No tiene"
      },
      {
        "id": "GARAGE-c4ca42",
        "name": "1"
      },
      {
        "id": "GARAGE-c81e72",
        "name": "2"
      },
      {
        "id": "GARAGE-eccbc8",
        "name": "3"
      },
      {
        "id": "GARAGE-a87ff6",
        "name": "4"
      },
      {
        "id": "GARAGE-caf5ad",
        "name": "Más de 4"
      }
    ],
    "attribute_group_id": "ADICIONALES",
    "attribute_group_name": "Adicionales"
  },
  {
    "id": "MLA79242-COCINA",
    "name": "Cocina",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-COCINA-N",
        "name": "No"
      },
      {
        "id": "MLA79242-COCINA-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-INTERNET",
    "name": "Conexión a Internet",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-INTERNET-N",
        "name": "No"
      },
      {
        "id": "MLA79242-INTERNET-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-DEPOSITO",
    "name": "Depósito",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-DEPOSITO-N",
        "name": "No"
      },
      {
        "id": "MLA79242-DEPOSITO-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-ENTREPISO",
    "name": "Entrepiso",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-ENTREPISO-N",
        "name": "No"
      },
      {
        "id": "MLA79242-ENTREPISO-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-EXPENCEM",
    "name": "Expensas ($)",
    "value_type": "string",
    "value_max_length": 60,
    "tags": {
    },
    "attribute_group_id": "ADICIONALES",
    "attribute_group_name": "Adicionales"
  },
  {
    "id": "MLA79242-GRUPOELEC",
    "name": "Grupo eletrógeno",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-GRUPOELEC-N",
        "name": "No"
      },
      {
        "id": "MLA79242-GRUPOELEC-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-LUMINOS",
    "name": "Luminosidad",
    "value_type": "list",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-LUMINOS-BUENA",
        "name": "Buena"
      },
      {
        "id": "MLA79242-LUMINOS-MUY_BUENA",
        "name": "Muy buena"
      },
      {
        "id": "MLA79242-LUMINOS-REGULAR",
        "name": "Regular"
      }
    ],
    "attribute_group_id": "ADICIONALES",
    "attribute_group_name": "Adicionales"
  },
  {
    "id": "MLA79242-LINTELEF",
    "name": "Línea telefónica",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-LINTELEF-N",
        "name": "No"
      },
      {
        "id": "MLA79242-LINTELEF-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-SISTINCEN",
    "name": "Sistema contra incendio",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-SISTINCEN-N",
        "name": "No"
      },
      {
        "id": "MLA79242-SISTINCEN-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-TVCABLE",
    "name": "TV por cable",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-TVCABLE-N",
        "name": "No"
      },
      {
        "id": "MLA79242-TVCABLE-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  },
  {
    "id": "MLA79242-VESTU",
    "name": "Vestuario",
    "value_type": "boolean",
    "tags": {
    },
    "values": [
      {
        "id": "MLA79242-VESTU-N",
        "name": "No"
      },
      {
        "id": "MLA79242-VESTU-Y",
        "name": "Sí"
      }
    ],
    "attribute_group_id": "CARACTERISTICAS",
    "attribute_group_name": "Caracteristicas Adicionales"
  }

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.

  • X-Content-Created: contains the date of the last generation.
  • X-Content-MD5: contains the MD5 checksum of the last generation.
c~$ curl -I  https://api.mercadolibre.com/sites/MLB/categories/all
HTTP/1.1 200 OK
Server: nginx/1.0.4
Date: Tue, 24 Jul 2012 15:14:58 GMT
Content-Type: application/json;charset=UTF-8
Connection: keep-alive
X-MLAPI-Version: 1.9.5
Content-Encoding: gzip
X-Content-Created: 2012-07-24T14:00:59.716Z
X-Content-MD5: 943541196986770119b4af1e66bda2dc

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:

curl -X GET https://api.mercadolibre.com/sites/MLA/search?category=MLA5726

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

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:

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

This action retrieves a JSON data with an array of 3 items as shown:

{
  "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 retrieving the 50 items that follow the default response:
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 items starting from the first fifty 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=3
This action retrieves a JSON data with an array of 5 items as shown:

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



Next topic:
Locate your properties.

Please rate this

Manage users

If you registered your application, got authenticated and created a Test user successfully, the next step is to learn how to work with users (sellers and buyers).

Contents:

Register as a real estate agency (Optional)

If you are a real estate agency, you can register your user as such to gain access to our promotional real estate packs. To accomplish this, access the Help section. This step can’t be accessed through API, you need to follow the path: Ayuda > Configuración de mi cuenta > Registrarme como empresa, concesionaria e inmobiliaria.

Screenshot_4

Once you choose “Registrarme como Inmobiliaria” you’ll be redirected to a form which must be filled with the proper information and you will also be able to choose your desired promotional package. After completing the form, one of our agents will get in touch with you.

Keep in mind that having a promotional pack is not mandatory for listing through the API but it’s really helpful for real estate agencies. Learn how to work with Promotion Packs.

Get my personal data

If you are logged in MercadoLibre and have a token, you will be able to make the call below and learn about your user-related information:

Example:

 curl  - X GET https://api.mercadolibre.com/users/me?access_token=$ACCESS_TOKEN

Response:

{
  "id": 202593498,
  "nickname": "TETE2870021",
  "registration_date": "2016-01-06T11:31:42.000-04:00",
  "country_id": "AR",
  "address": {
	"state": "AR-C",
	"city": "Palermo"
  },
  "user_type": "real_estate_agency",
  "tags": [
	"real_estate_agency",
	"test_user",
	"user_info_verified"
  ],
  "logo": null,
  "points": 100,
  "site_id": "MLA",
  "permalink": "http://perfil.mercadolibre.com.ar/TETE2870021",
  "seller_reputation": {
	"level_id": null,
	"power_seller_status": null,
	"transactions": {
  	"period": "historic",
  	"total": 0,
  	"completed": 0,
  	"canceled": 0,
  	"ratings": {
    	"positive": 0,
    	"negative": 0,
    	"neutral": 0
  	}
	}
  },
  "buyer_reputation": {
	"tags": [
	]
  },
  "status": {
	"site_status": "active"
  }
}

As shown in the result, it is a –real estate- test user that has been active in the Argentine site since January 6th, 2016, with no relevant reputation data to date.

Get data from other users

If you want to query third-party user data, you will be able to identify two information levels: public data, which you can find navigating the MercadoLibre profile of any other user, e.g.: http://perfil.mercadolibre.com.ar/TETE2870021, and private data, which will be hidden unless you have user permission and a valid token to work on his/her behalf.
In both cases, first you need to know the user ID.

How to get a user’s ID?

If you do not have the ID but you know the user’s nickname and the site he/she belongs to, you will be able to get their ID using the following search:

Call:

https://api.mercadolibre.com/sites/{Site_id}/search?nickname={Nickname}

Example:

https://api.mercadolibre.com/sites/MLA/search?nickname=TETE2870021

Response:

{
  "site_id": "MLA",
  "seller": {
	"id": 202593498,
	"seller_reputation": {
  	"power_seller_status": null
	},
	"real_estate_agency": false,
	"car_dealer": false,
	"tags": [
	]
  },
  "paging": {
	"total": 2,
	"offset": 0,
	"limit": 50
  },
  "results": [
	{
  	"id": "MLA598903377",
  	"site_id": "MLA",
  	"title": "Test Item - Nao Ofertar",
  	"subtitle": null,
  	"seller": {
    	"id": 202593498,
    	"power_seller_status": null,
    	"car_dealer": false,
    	"real_estate_agency": false,
    	"tags": [
    	]
  	},
  	"price": 200,
  	"currency_id": "ARS",
  	"available_quantity": 1,
  	"sold_quantity": 0,
  	"buying_mode": "buy_it_now",
  	"listing_type_id": "bronze",
  	"stop_time": "2016-03-06T17:16:49.000Z",
  	"condition": "new",
  	"permalink": "http://articulo.mercadolibre.com.ar/MLA-598903377-test-item-nao-ofertar-_JM",
  	"thumbnail": "http://mla-s2-p.mlstatic.com/546311-MLA20539702714_012016-I.jpg",
  	"accepts_mercadopago": true,
  	"installments": {
    	"quantity": 6,
    	"amount": 42.33,
    	"currency_id": "ARS"
  	},
  	"address": {
    	"state_id": "AR-C",
    	"state_name": "Capital Federal",
    	"city_id": "",
    	"city_name": "Palermo"
  	},
  	"shipping": {
    	"free_shipping": false,
    	"mode": "not_specified"
  	},
  	"seller_address": {
    	"id": 175597910,
    	"comment": "",
    	"address_line": "",
    	"zip_code": "",
    	"country": {
      	"id": "AR",
      	"name": "Argentina"
    	},
    	"state": {
      	"id": "AR-C",
      	"name": "Capital Federal"
    	},
    	"city": {
      	"id": "",
      	"name": "Palermo"
   	 },
    	"latitude": -34.571148,
    	"longitude": -58.423298
  	},
  	"attributes": [
  	],
  	"original_price": null,
  	"category_id": "MLA374515",
  	"official_store_id": null
	},
	{
  	"id": "MLA599121050",
  	"site_id": "MLA",
  	"title": "Item De Test - No Ofertar",
  	"subtitle": null,
  	"seller": {
    	"id": 202593498,
    	"power_seller_status": null,
    	"car_dealer": false,
    	"real_estate_agency": false,
    	"tags": [
    	]
  	},
  	"price": 1000,
  	"currency_id": "ARS",
  	"available_quantity": 1,
  	"sold_quantity": 0,
  	"buying_mode": "buy_it_now",
  	"listing_type_id": "bronze",
  	"stop_time": "2016-03-07T20:12:41.000Z",
  	"condition": "new",
  	"permalink": "http://articulo.mercadolibre.com.ar/MLA-599121050-item-de-test-no-ofertar-_JM",
  	"thumbnail": "http://mla-s2-p.mlstatic.com/493311-MLA20538550251_012016-I.jpg",
  	"accepts_mercadopago": true,
  	"installments": {
    	"quantity": 6,
        "amount": 211.65,
    	"currency_id": "ARS"
  	},
  	"address": {
    	"state_id": "AR-C",
    	"state_name": "Capital Federal",
    	"city_id": "",
    	"city_name": "Palermo"
  	},
  	"shipping": {
    	"free_shipping": false,
    	"mode": "not_specified"
  	},
  	"seller_address": {
    	"id": 175597910,
    	"comment": "",
    	"address_line": "",
    	"zip_code": "",
    	"country": {
      	"id": "AR",
      	"name": "Argentina"
    	},
    	"state": {
  	    "id": "AR-C",
      	"name": "Capital Federal"
    	},
    	"city": {
      	"id": "",
      	"name": "Palermo"
    	},
    	"latitude": -34.571148,
    	"longitude": -58.423298
  	},
  	"attributes": [
  	],
  	"original_price": null,
  	"category_id": "MLA90105",
  	"official_store_id": null
	}
  ],
  "secondary_results": [
  ],
  "related_results": [
  ],
  "sort": {
	"id": "relevance",
	"name": "More relevant"
  },
  "available_sorts": [
	{
 	 "id": "price_asc",
  	"name": "Lower price"
	},
	{
  	"id": "price_desc",
  	"name": "Higher price"
	}
  ],
  "filters": [
  ],
  "available_filters": [
	{
  	"id": "category",
  	"name": "Categories",
  	"type": "text",
	  "values": [
    	{
      	"id": "MLA1648",
      	"name": "Computación",
      	"results": 1
    	},
    	{
      	"id": "MLA1430",
      	"name": "Ropa y Accesorios",
      	"results": 1
    	}
  	]
	},
	{
  	"id": "state",
  	"name": "Location",
  	"type": "text",
  	"values": [
    	{
      	"id": "TUxBUENBUGw3M2E1",
      	"name": "Capital Federal",
      	"results": 2
    	}
  	]
	},
	{
  	"id": "accepts_mercadopago",
 	 "name": "MercadoPago filter",
  	"type": "boolean",
  	"values": [
    	{
      	"id": "yes",
      	"name": "With MercadoPago",
      	"results": 2
    	}
  	]
	},
	{
  	"id": "installments",
  	"name": "Pago",
  	"type": "text",
  	"values": [
    	{
      	"id": "yes",
      	"name": "Installments",
      	"results": 2
    	},
    	{
      	"id": "no_interest",
      	"name": "Sin interés",
      	"results": 0
    	}
  	]
	},
	{
  	"id": "condition",
  	"name": "Condition filter",
  	"type": "text",
  	"values": [
    	{
      	"id": "new",
      	"name": "New",
      	"results": 2
    	}
  	]
	},
	{
  	"id": "buying_mode",
  	"name": "Buying mode filter",
  	"type": "text",
  	"values": [
    	{
      	"id": "buy_it_now",
      	"name": "Buy it now",
      	"results": 2
    	}
  	]
	},
	{
  	"id": "has_pictures",
  	"name": "Items with images filter",
  	"type": "boolean",
  	"values": [
    	{
      	"id": "yes",
      	"name": "With pictures",
      	"results": 2
    	}
  	]
	}
  ]
}

Get a user’s public information

Now, as you already know the user ID, you can make a call to the users’ resource as shown below in order to get the public information of the user you want:

Call:

curl GET -X  https://api.mercadolibre.com/users/{User_id}

Example:

GET -X  https://api.mercadolibre.com/users/202593498

Response:

{
  "id": 202593498,
  "nickname": "TETE2870021",
  "registration_date": "2016-01-06T11:31:42.000-04:00",
  "country_id": "AR",
  "address": {
    "state": "AR-C",
	"city": "Palermo"
  },
  "user_type": "normal",
  "tags": [
	"normal",
	"test_user",
	"user_info_verified"
  ],
  "logo": null,
  "points": 100,
  "site_id": "MLA",
  "permalink": "http://perfil.mercadolibre.com.ar/TETE2870021",
  "seller_reputation": {
	"level_id": null,
	"power_seller_status": null,
	"transactions": {
  	"period": "historic",
  	"total": 0,
  	"completed": 0,
  	"canceled": 0,
  	"ratings": {
    	"positive": 0,
    	"negative": 0,
    	"neutral": 0
  	}
	}
  },
  "buyer_reputation": {
	"tags": [
	]
  },
  "status": {
	"site_status": "active"
  }
}

Get private information of a user who accepted the use of my application

In order to get a user’s private data, you just need to know the user’s ACCESS_TOKEN at the end of the call that you made before.

Call:

curl GET -X  https://api.mercadolibre.com/users/{User_id}?access_token=¢ACCESS_TOKEN

Example:

curl GET -X  https://api.mercadolibre.com/users/202593498?access_token=¢ACCESS_TOKEN

Response:

{
  "id": 202593498,
  "nickname": "TETE2870021",
  "registration_date": "2016-01-06T11:31:42.000-04:00",
  "first_name": "Test",
  "last_name": "Test",
  "country_id": "AR",
  "email": "test_user_50698062@testuser.com",
  "identification": {
	"type": "DNI",
	"number": "1111111"
  },
  "address": {
	"state": "AR-C",
	"city": "Palermo",
	"address": "Test Address 123",
	"zip_code": "1414"
  },
  "phone": {
	"area_code": "01",
	"number": "1111-1111",
	"extension": "",
	"verified": false
  },
  "alternative_phone": {
	"area_code": "",
	"number": "",
	"extension": ""
  },
  "user_type": "real_estate_agency",
  "tags": [
	"real_estate_agency",
	"test_user",
	"user_info_verified"
  ],
  "logo": null,
  "points": 100,
  "site_id": "MLA",
  "permalink": "http://perfil.mercadolibre.com.ar/TETE2870021",
  "shipping_modes": [
	"custom",
	"not_specified"
  ],
  "seller_experience": "ADVANCED",
  "seller_reputation": {
	"level_id": null,
	"power_seller_status": null,
	"transactions": {
  	"period": "historic",
  	"total": 0,
  	"completed": 0,
  	"canceled": 0,
  	"ratings": {
    	"positive": 0,
    	"negative": 0,
    	"neutral": 0
  	}
	}
  },
  "buyer_reputation": {
	"canceled_transactions": 0,
	"transactions": {
  	"period": "historic",
  	"total": null,
  	"completed": null,
  	"canceled": {
    	"total": null,
    	"paid": null
  	},
  	"unrated": {
    	"total": null,
    	"paid": null
  	},
  	"not_yet_rated": {
    	"total": null,
    	"paid": null,
    	"units": null
  	}
	},
	"tags": [
	]
  },
  "status": {
	"site_status": "active",
	"list": {
  	"allow": true,
  	"codes": [
  	],
  	"immediate_payment": {
    	"required": false,
    	"reasons": [
    	]
  	}
	},
	"buy": {
  	"allow": true,
  	"codes": [
  	],
  	"immediate_payment": {
    	"required": false,
    	"reasons": [
    	]
  	}
	},
	"sell": {
	  "allow": true,
  	"codes": [
  	],
  	"immediate_payment": {
    	"required": false,
    	"reasons": [
    	]
  	}
	},
	"billing": {
  	"allow": true,
  	"codes": [
  	]
	},
	"mercadopago_tc_accepted": true,
	"mercadopago_account_type": "personal",
	"mercadoenvios": "not_accepted",
	"immediate_payment": false,
	"confirmed_email": false,
	"user_type": "eventual",
	"required_action": ""
  },
  "credit": {
	"consumed": 100,
	"credit_level_id": "MLA1"
  }
}

As you can see, this time you got more information about the user: full name, e-mail, telephone, address, etc. Please do not disclose this data since it may jeopardize the user.

Update user’s information

You can use our resources to update your user information after registration. This is a common issue, since at this instance you’re not asked to fill your address or personal identification, but you need to have them filled or you’ll be unable to list items on MercadoLibre.
To update your user information, follow the example:

Example:

curl -X PUT -H "Content-Type: application/json" -d
{
"identification_type": "DNI",
"identification_number": "33333333",
"address": "Triunvirato 5555",
"state":"AR-C",
"city":"Capital Federal",
"zip_dode": "1431",
"phone":{
        "area_code":"011",
        "number":"4444-4444",
        "extension":"001"
    	},
"first_name":"Pedro",
"last_name": "Picapiedras",
"company":{
          "corporate_name":"Acme",
          "brand_name":"Acme Company"
      	},
"mercadoenvios": "accepted"
}

https://api.mercadolibre.com/users/{User_id}?access_token=

Congratulations, you’ve updated your user Information. Remember to only send the fields you want to update.

Common error codes

206 – Partial content: in some cases Users API resource will return a 206 – Partial Content code. This is going to happen when the request to some of the data fails (for example, user reputation), to make you aware that you’re getting an incomplete response.



Next topic: Choose operation and property type


Related article:
Learn how to manage user’s addresses.

Please rate this

Real Estate Guide

Real estate is classified listings where sellers’ contact data is public, which makes it easier for buyers to contact directly with sellers, and payment and engagement conditions are agreed between the parties without bid.


You can create applications to list real estate and take contact metrics, search by geolocation, share prices and features, add to favorites, send reminders, suggest similar listings, etc.




Next topic: Authenticate



Related article:
Follow our authentication guide to start working with our API.

Please rate this