# Metros Cubicos Property Search API Documentation

Scrappa's `GET /api/metroscubicos/search` returns Metros Cubicos property listings in Mexico as structured JSON, for sale (`operation=sale`, the default) or for rent (`rent`).

## What you get

One request returns one page of up to 48 listings and the site's own match count in `total`. Each listing has `id`, `url` (the public listing page on Mercado Libre Mexico, the source of the data; its id feeds the listing endpoint), `title`, `price` (amount, currency, `from` for developments), `attributes` (bedrooms, bathrooms, parking and area as ranges plus the raw card text), `location` text, one `image`, and development fields (`is_development`, `delivery`, `units_available`). Search cards carry no coordinates. Call the listing endpoint for the description, fees, coordinates and all photos.

## Filters are honoured

The site applies every filter itself. Scrappa then checks each card once more against price, bedrooms, bathrooms and area and drops a card whose own values contradict the filter. The number of dropped cards is `meta.filtered_out`, so a page can hold fewer than 48 listings. `total` stays the site's count and does not shrink by `filtered_out`. A card that does not show a value (a studio shows no bedrooms, many cards show no area) cannot be contradicted and stays.

- Developments show ranges such as `2 a 3 dormitorios`. They are kept when the range contains the requested bedrooms.
- `bathrooms` counts full bathrooms. A card may count half bathrooms too and show a higher number.
- `price_min` and `price_max` are in MXN. The area is checked only when the card shows the same kind of area (`built` or `total`).
- `bedrooms=4` means four or more. `bathrooms=3` means three or more.
- Unknown parameters are rejected with `422` instead of being ignored. `applied_filters` echoes what was sent.

## Locations

`state` takes a slug from `/api/metroscubicos/locations`, for example `jalisco`. `city` takes a city or borough slug of that state and needs `state`. An unknown state or city returns a non-billable `422` (`unknown_location`). Without `state` the search covers all of Mexico.

## Sort and pagination

`sort` is `default` (relevance), `price_asc` or `price_desc`. `page` is 1-based with 48 listings per page. The site serves the first 42 pages of any search, so `page` goes up to 42; narrow the filters to reach other listings. A page past the last result page returns an empty list with `total` 0. It never returns another page's listings.

- **Documentation:** [https://scrappa.co/docs/metroscubicos-api/metroscubicos_search](https://scrappa.co/docs/metroscubicos-api/metroscubicos_search)
- **API group:** Metros Cubicos API
- **Endpoint:** `GET https://scrappa.co/api/metroscubicos/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `operation` | string | No | sale (default) or rent. |
| `type` | string | No | apartment (default), house, land, office, commercial, warehouse, building, room, ranch or hacienda. |
| `state` | string | No | State slug from /api/metroscubicos/locations, for example jalisco or distrito-federal. |
| `city` | string | No | City or borough slug of the state from /api/metroscubicos/locations?state=..., for example zapopan. Needs state. |
| `price_min` | integer | No | Minimum price in MXN. |
| `price_max` | integer | No | Maximum price in MXN. |
| `bedrooms` | integer | No | 0 (studio) to 4 (four or more). |
| `bathrooms` | integer | No | Full bathrooms, 1 to 3 (three or more). |
| `area_min` | number | No | Minimum area in square metres. |
| `area_max` | number | No | Maximum area in square metres. |
| `area_type` | string | No | built (default) or total. Land searches use total by default. Needs area_min or area_max. |
| `sort` | string | No | default, price_asc or price_desc. |
| `page` | integer | No | Result page, 1 to 42. 48 listings per page. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/metroscubicos/search?operation=sale&type=apartment&state=distrito-federal&bedrooms=2&price_max=6000000&sort=price_asc"
```

## Example response

```json
{
    "success": true,
    "total": 3120,
    "returned": 1,
    "pagination": {
        "page": 1,
        "limit": 48,
        "pages_count": 42,
        "has_next_page": true,
        "has_previous_page": false
    },
    "applied_filters": {
        "operation": "sale",
        "type": "apartment",
        "state": "distrito-federal",
        "bedrooms": 2,
        "price_max": 6000000,
        "sort": "price_asc"
    },
    "listings": [
        {
            "id": "MLM-6326040252",
            "title": "Splendor Coyoacan",
            "url": "https://departamento.mercadolibre.com.mx/MLM-6326040252-splendor-coyoacan-_JM",
            "headline": "Departamento en venta",
            "is_development": true,
            "price": {
                "amount": 5371700,
                "currency": "MXN",
                "from": true
            },
            "attributes": {
                "bedrooms": {
                    "min": 2,
                    "max": 3
                },
                "bathrooms": {
                    "min": 2,
                    "max": 2
                },
                "parking": null,
                "area": {
                    "min": 64,
                    "max": 95,
                    "kind": "built"
                },
                "raw": [
                    "2 a 3 dormitorios",
                    "2 ba\u00f1os",
                    "64 - 95 m\u00b2 construidos"
                ]
            },
            "location": "Avenida Divisi\u00f3n Del Norte 2325, Benito Ju\u00e1rez, Distrito Federal",
            "image": "https://http2.mlstatic.com/D_NQ_NP_2X_666237-MLM118578393547_102026-E.webp",
            "delivery": "Pronta entrega",
            "units_available": "3 unidades disponibles",
            "featured": true,
            "seller": null
        }
    ],
    "meta": {
        "endpoint_family": "search",
        "billable": true,
        "attempts": 1,
        "filtered_out": 2
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Unknown Location | The `state` or `city` slug is not known to Metros Cubicos (`unknown_location`). The site would turn it into a text search, so the request is rejected. Non-billable. |
| 422 | Validation Error | A query parameter is missing, unknown or unusable. Unknown parameters are rejected, never ignored. Non-billable. |
| 503 | Upstream Unavailable | Metros Cubicos could not be reached after retries, answered with an error, or returned an unexpected answer (`upstream_unavailable`, `upstream_blocked`, `upstream_changed`). Retryable and never billed. Clients are never rate limited. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)