# OneRoof Autocomplete API Documentation

<p><strong>OneRoof Autocomplete API</strong> finds places by name. Each area in <code>locations</code> and <code>surrounding_suburbs</code> has <code>search_params</code>, ready to add to a search request, for example <code>{"suburb_id": 3236}</code>. Properties carry a <code>listing_id</code> for the listing route. Streets, schools and projects are returned with their coordinates. Failed requests are not billed.</p>

- **Documentation:** [https://scrappa.co/docs/oneroof-api/oneroof_autocomplete](https://scrappa.co/docs/oneroof-api/oneroof_autocomplete)
- **API group:** OneRoof API
- **Endpoint:** `GET https://scrappa.co/api/oneroof/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 | Required. A place, street, school or address, 2 to 100 characters. |
| `type` | string | No | sale (default), rent or sold. Limits the properties that are suggested. |

## Example response

```json
{
    "data": {
        "schools": [
            {
                "id": 275,
                "name": "Ponsonby Primary School",
                "level": "Contributing",
                "address": "44 Curran Street, Herne Bay, Auckland",
                "latitude": -36.842089,
                "longitude": 174.738996
            },
            {
                "id": 2663,
                "name": "Ponsonby Kindergarten",
                "level": "Free Kindergarten",
                "address": "22 Ponsonby Terrace, Ponsonby, Auckland",
                "latitude": -36.850131,
                "longitude": 174.742038
            }
        ],
        "streets": [
            {
                "id": 17677,
                "label": "Sheehan Street, Ponsonby, Auckland",
                "latitude": -36.84792129165,
                "longitude": 174.7420053583
            },
            {
                "id": 24429,
                "label": "Stuart Street, Ponsonby, Auckland",
                "latitude": -36.85299225,
                "longitude": 174.74031321665
            }
        ],
        "projects": [],
        "locations": [
            {
                "id": 3236,
                "name": "Ponsonby",
                "slug": "ponsonby-auckland-city-3236",
                "label": "Ponsonby, Auckland City",
                "level": "suburb",
                "latitude": -36.85075878778,
                "longitude": 174.73915915575,
                "listing_count": 25,
                "search_params": {
                    "suburb_id": 3236
                },
                "median_sale_price": null
            }
        ],
        "properties": [
            {
                "slug": "property/auckland/ponsonby/217-ponsonby-road/gP6jt",
                "label": "217 Ponsonby Road, Ponsonby, Auckland City, Auckland, 933834",
                "latitude": null,
                "longitude": null,
                "listing_id": 2448804
            },
            {
                "slug": "property/auckland/ponsonby/33-summer-street/eaVYb",
                "label": "33 Summer Street, Ponsonby, Auckland City, Auckland, 1673025",
                "latitude": null,
                "longitude": null,
                "listing_id": 2537908
            }
        ],
        "surrounding_suburbs": [
            {
                "id": 1454,
                "name": "Freemans Bay",
                "slug": "freemans-bay-auckland-city-1454",
                "label": "Freemans Bay, Auckland City",
                "level": "suburb",
                "latitude": -36.853026650394,
                "longitude": 174.7503010005,
                "listing_count": 55,
                "search_params": {
                    "suburb_id": 1454
                },
                "median_sale_price": null
            },
            {
                "id": 677,
                "name": "Grey Lynn",
                "slug": "grey-lynn-auckland-city-677",
                "label": "Grey Lynn, Auckland City",
                "level": "suburb",
                "latitude": -36.859956441943,
                "longitude": 174.74008729504,
                "listing_count": 69,
                "search_params": {
                    "suburb_id": 677
                },
                "median_sale_price": null
            }
        ]
    },
    "meta": {
        "billable": true,
        "endpoint_family": "autocomplete"
    },
    "success": true
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A parameter is missing or invalid. This response is not billable. |
| 503 | Upstream Unavailable | OneRoof could not be reached. This response is not billable and is retryable. |

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