# ViewIt Rental Search API Documentation

Scrappa's `GET /api/viewit/search` returns the ViewIt rentals of one Canadian city, with filters and paging.

## What you get

`items`, each with `listing_id`, `detail_path`, `url`, `address`, `bedrooms_label`, `bedrooms`, `unit_type` (apartment, bachelor or room), `price` (CAD, null when the listing says "Call"), `price_from` (true for "from" prices), `latitude`, `longitude`, `photo`, `description`, `sponsored` and `has_video`. The `pagination` object holds `page`, `per_page`, `total`, `total_pages`, `range_from`, `range_to` and `has_next_page`.

## Limits

ViewIt lists rentals only. There is no sale mode. A page holds 5 listings and there is no sort: the order is the order of the site. `page` is 1 to 20, so one query reaches 100 results. Narrow the filters to reach the rest; `pagination.capped` says when a query has more.

## Filters are honoured

Every filter is applied by ViewIt and checked again on each item. A sponsored card ignores filters on the site, so a filtered search removes sponsored cards. A rental with no price ("Call") is removed when a price filter is set. Removed items are counted in `items_dropped`, and `total_includes_dropped` says when `pagination.total` contains them. A page the site did not serve is never relabelled: a page past the last page returns `422` `PAGE_OUT_OF_RANGE`.

## Bedrooms

`bedrooms` is a comma list of `room`, `bachelor`, `1`, `2` and `3plus` (three or more). Example: `bedrooms=1,2`.

- **Documentation:** [https://scrappa.co/docs/viewit-api/viewit_search](https://scrappa.co/docs/viewit-api/viewit_search)
- **API group:** ViewIt API
- **Endpoint:** `GET https://scrappa.co/api/viewit/search`

## 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 |
| --- | --- | --- | --- |
| `city_id` | integer | Yes | City id from the autocomplete endpoint, for example 14 (Toronto) or 34 (Ottawa). |
| `bedrooms` | string | No | Comma list of room, bachelor, 1, 2 and 3plus (three or more). Example: 1,2. |
| `price_min` | integer | No | Minimum monthly rent in CAD. Checked again on every item. |
| `price_max` | integer | No | Maximum monthly rent in CAD. Checked again on every item. |
| `keyword` | string | No | Word the listing text must contain, for example parking, downtown or university. |
| `furnished` | boolean | No | Send true to see furnished rentals only. |
| `loft` | boolean | No | Send true to see lofts only. |
| `retirement` | boolean | No | Send true to see retirement residences only. |
| `short_term` | boolean | No | Send true to see short term rentals only. |
| `page` | integer | No | Result page, 1 to 20. A page holds up to 5 listings. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/viewit/search?city_id=14&bedrooms=2&price_max=2500"
```

## Example response

```json
{
    "success": true,
    "data": {
        "items": [
            {
                "listing_id": 3844,
                "detail_path": "468470SummerhillAve-Toronto-2bdrm-VIT=3844",
                "url": "https://www.viewit.ca/468470SummerhillAve-Toronto-2bdrm-VIT=3844",
                "address": "468, 470 Summerhill Ave",
                "bedrooms_label": "2 bds",
                "bedrooms": 2,
                "unit_type": "apartment",
                "price": 2200,
                "price_from": false,
                "currency": "CAD",
                "latitude": 43.686504,
                "longitude": -79.374658,
                "photo": "https://images.viewit.ca/3844/Image058.jpg",
                "description": "Available immediately. Beautiful Rosedale. Totally renovated 2 bedroom with dishwasher.",
                "sponsored": false,
                "has_video": true
            }
        ],
        "pagination": {
            "page": 1,
            "per_page": 5,
            "total": 27,
            "total_pages": 6,
            "max_pages": 20,
            "capped": false,
            "range_from": 1,
            "range_to": 5,
            "has_next_page": true
        },
        "items_dropped": 0,
        "total_includes_dropped": true,
        "applied_filters": {
            "city_id": 14,
            "bedrooms": "2",
            "price_max": 2500
        }
    },
    "meta": {
        "endpoint_family": "search",
        "billable": true,
        "attempts": 1,
        "items_dropped": 0
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A query parameter is missing, unknown or unusable. Unknown parameters and unknown values are rejected, never ignored. Non-billable. |
| 422 | Page Out of Range | The page is past the last page of results (`PAGE_OUT_OF_RANGE`). ViewIt serves at most 20 pages (100 results) per query: narrow the filters, for example with a price band. Non-billable. |
| 503 | Upstream Unavailable | ViewIt could not be reached, refused the request or answered with a page this API could not read (`UPSTREAM_UNAVAILABLE`). 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)