# Metros Cubicos Location Autocomplete API Documentation

Scrappa's `GET /api/metroscubicos/locations` returns the places the search accepts. Metros Cubicos has no place tree, so the endpoint works in three modes.

## Modes

- No parameter: the 32 Mexican states with their slug. This answer is fixed and makes no lookup on the site.
- `state`: the cities and boroughs of that state with the number of listings, taken from the filters of the state's result page. The site shows only the nine places with the most listings; any other city slug (the lowercase name with hyphens) still works in the search. Each `slug` works in the search `city` parameter. `operation` and `type` choose which listings the counts describe (sale and apartment by default).
- `q`: search suggestions for a text, such as `casa polanco`. Suggestions are text queries, not ids. Use them as ideas for your own search.

Use either `q` or `state`, not both. An unknown `state` returns a non-billable `422` (`unknown_location`).

## Response

`mode` is `states`, `cities` or `suggestions`. `locations` holds objects with `type`, `slug`, `name` and `listings` (`null` where the site gives no count). `state` names the state in cities mode.

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

## 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 |
| --- | --- | --- | --- |
| `q` | string | No | Search text, at least 2 characters. Returns suggestions. |
| `state` | string | No | State slug, for example jalisco. Returns its cities. |
| `operation` | string | No | sale (default) or rent. Chooses the listings the city counts describe. |
| `type` | string | No | Property type for the city counts: apartment (default), house, land, office, commercial, warehouse, building, room, ranch or hacienda. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/metroscubicos/locations?state=jalisco"
```

## Example response

```json
{
    "success": true,
    "mode": "cities",
    "state": {
        "slug": "jalisco",
        "name": "Jalisco"
    },
    "count": 1,
    "locations": [
        {
            "type": "city",
            "slug": "zapopan",
            "name": "Zapopan",
            "listings": 9100
        }
    ],
    "meta": {
        "endpoint_family": "locations",
        "billable": true,
        "attempts": 1
    }
}
```

## 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)