# Urbania Location Autocomplete API Documentation

Resolve free text into Peruvian places. Each item has the id, the name, the level, the full label and the slug. Pass the slug as the location of /search. A query that matches nothing returns an empty list as a successful response.

- **Documentation:** [https://scrappa.co/docs/urbania-api/urbania_autocomplete](https://scrappa.co/docs/urbania-api/urbania_autocomplete)
- **API group:** Urbania API
- **Endpoint:** `GET https://scrappa.co/api/urbania/autocomplete`

## 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 | Yes | Free text, 2 to 80 characters. Example: miraflores. |
| `limit` | integer | No | Number of suggestions, 1 to 20. Defaults to 8. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/urbania/autocomplete?q=miraflores&limit=5"
```

## Example response

```json
{
    "success": true,
    "data": {
        "items": [
            {
                "id": "V1-D-119497",
                "name": "Miraflores",
                "level": "barrio",
                "label": "Miraflores, Lima, Lima",
                "slug": "miraflores--lima--lima"
            }
        ],
        "query": "miraflores"
    },
    "meta": {
        "endpoint_family": "autocomplete",
        "billable": true
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A public parameter is missing or invalid, or the location cannot be resolved. The response is not billable. |
| 404 | Resource Not Found | No Urbania resource matches the request. The response is not billable. |
| 503 | Unexpected Upstream Response | Urbania answered with a page in an unexpected format. The response is not billable. |
| 503 | Upstream Unavailable | Urbania was temporarily unavailable or blocked the request. The response is not billable and the request never answers 429. |

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