# Goplaceit Location Autocomplete API Documentation

Scrappa's `GET /api/goplaceit/location-autocomplete` finds regions and communes by name. Send `q` (at least 2 characters) and `country`.

## What you get

Each match has `id`, `name`, `level` (`region` or `commune`), the `region` it belongs to, `latitude`, `longitude` and `search_param`, the name of the search parameter to send the id in. Matching ignores accents and case. Names that start with the text come first.

## Built from cached lists

Goplaceit has no text suggest service, so Scrappa matches over its region and commune lists. The first request for a country after 24 hours builds that index from the lists, which can take several seconds. Later requests are served from the cache and cost no source lookup (`meta.cached`). Neighborhoods are not part of the index: use locations with `commune`.

## Mexico

Mexican regions hold thousands of communes (about 25 MB in total), so for `country=mx` the index holds the regions only and `meta.communes_included` is `false`. Send `region` (an id from a first search) to match the communes of that one region. That region list is loaded once and cached for 24 hours. For Chile and Colombia the index holds every commune and `region` only narrows the matches.

- **Documentation:** [https://scrappa.co/docs/goplaceit-api/goplaceit_location_autocomplete](https://scrappa.co/docs/goplaceit-api/goplaceit_location_autocomplete)
- **API group:** Goplaceit API
- **Endpoint:** `GET https://scrappa.co/api/goplaceit/location-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 | Start or part of a place name, at least 2 characters. |
| `country` | string | Yes | cl, mx or co. |
| `region` | integer | No | Region id. Limits matches to that region. Needed to find communes in Mexico. |
| `limit` | integer | No | Matches to return, 1-20 (default 20). |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/goplaceit/location-autocomplete?q=providencia&country=cl"
```

## Example response

```json
{
    "success": true,
    "query": "providencia",
    "country": "cl",
    "total_results": 1,
    "returned": 1,
    "locations": [
        {
            "id": 297,
            "name": "Providencia",
            "level": "commune",
            "region": {
                "id": 13,
                "name": "Region Metropolitana"
            },
            "latitude": -33.4314,
            "longitude": -70.6093,
            "search_param": "commune"
        }
    ],
    "meta": {
        "endpoint_family": "location-autocomplete",
        "billable": true,
        "cached": true,
        "attempts": 0,
        "communes_included": true
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A query parameter is missing, unknown or unusable. Unknown parameters and unknown sort or type values are rejected, never ignored. Non-billable. |
| 503 | Source Unavailable | Goplaceit could not be reached in time, refused the request, or its answer changed shape (`upstream_unavailable`, `request_blocked`, `deadline_exhausted`, `parser_drift`). 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)