# Adondevivir Locations API Documentation

Resolve free text into provinces, departments, districts and zones of Peru. Each item has the id, the name, the level and the full place name. Pass the search_param of an item as the location filter of /search. A text that matches nothing returns an empty list as a successful response.

- **Documentation:** [https://scrappa.co/docs/adondevivir-api/adondevivir_locations](https://scrappa.co/docs/adondevivir-api/adondevivir_locations)
- **API group:** Adondevivir API
- **Endpoint:** `GET https://scrappa.co/api/adondevivir/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 |
| --- | --- | --- | --- |
| `query` | string | Yes | Place name, 2 to 80 characters. Example: miraflores. |
| `limit` | integer | No | Number of suggestions, 1 to 20. Defaults to 10. |

## Example request

```bash
#!/bin/bash

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

## Example response

```json
{
    "success": true,
    "data": {
        "items": [
            {
                "id": "V1-D-119497",
                "name": "Miraflores",
                "label": "barrio",
                "label_suggest": "Miraflores, Lima, Lima",
                "level": "district",
                "search_param": "V1-D-119497"
            },
            {
                "id": "V1-D-119504",
                "name": "San Juan de Miraflores",
                "label": "barrio",
                "label_suggest": "San Juan de Miraflores, Lima, Lima",
                "level": "district",
                "search_param": "V1-D-119504"
            },
            {
                "id": "V1-E-1844",
                "name": "Aurora",
                "label": "zona",
                "label_suggest": "Aurora, Miraflores, Lima, Lima",
                "level": "zone",
                "search_param": "V1-E-1844"
            }
        ],
        "count": 3
    },
    "meta": {
        "endpoint_family": "locations",
        "billable": true
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A public parameter is missing or invalid. The response is not billable. |
| 404 | Resource Not Found | The requested Adondevivir resource does not exist. The response is not billable. |
| 503 | Unexpected Upstream Response | Adondevivir answered with a body that is not the documented shape. The response is not billable. |
| 503 | Upstream Unavailable | Adondevivir 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)