# Plusvalia Locations API Documentation

Resolve free text into provinces, cities and zones of Ecuador. 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/plusvalia-api/plusvalia_locations](https://scrappa.co/docs/plusvalia-api/plusvalia_locations)
- **API group:** Plusvalia API
- **Endpoint:** `GET https://scrappa.co/api/plusvalia/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: cumbaya. |
| `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/plusvalia/locations?query=cumbaya&limit=5"
```

## Example response

```json
{
    "success": true,
    "data": {
        "items": [
            {
                "id": "V1-D-6",
                "name": "Cumbay\u00e1",
                "label": "barrio",
                "label_suggest": "Cumbay\u00e1, Quito, Pichincha",
                "level": "zone",
                "search_param": "V1-D-6"
            },
            {
                "id": "V1-D-101004658",
                "name": "San Juan de Cumbay\u00e1",
                "label": "barrio",
                "label_suggest": "San Juan de Cumbay\u00e1, Quito, Pichincha",
                "level": "zone",
                "search_param": "V1-D-101004658"
            },
            {
                "id": "V1-D-101004659",
                "name": "San Patricio de Cumbay\u00e1",
                "label": "barrio",
                "label_suggest": "San Patricio de Cumbay\u00e1, Quito, Pichincha",
                "level": "zone",
                "search_param": "V1-D-101004659"
            }
        ],
        "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 Plusvalia resource does not exist. The response is not billable. |
| 503 | Unexpected Upstream Response | Plusvalia answered with a body that is not the documented shape. The response is not billable. |
| 503 | Upstream Unavailable | Plusvalia 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)