# VRTO Public Directory API

Read-only access to VRTO's rent-to-own store directory. This is the documentation
target for `rel="service-doc"`; the machine-readable description is
[`/openapi.json`](/openapi.json) and the catalog is
[`/.well-known/api-catalog`](/.well-known/api-catalog).

## Authentication

None. There is no account, key, or token. See [`/auth.md`](/auth.md).

## Endpoints

### `GET /api/search`

Typeahead search across cities, companies and store locations in the retail
directory.

| Parameter | Required | Description |
|---|---|---|
| `q` | yes | Search term: a city, company or store name (2–100 characters). |

```
GET /api/search?q=columbus
```

```json
{
  "results": [
    {
      "type": "city",
      "name": "Columbus, OH",
      "slug": "columbus",
      "state": "OH",
      "state_slug": "ohio",
      "store_count": 15,
      "url": "/ohio/columbus/"
    }
  ]
}
```

`type` is one of `city`, `company` or `store`. Fields present vary by type.
`url` is a path on vrto.com you can link a user to.

### `GET /api/companies`

Operators in the retail directory with at least one open location.

| Parameter | Required | Description |
|---|---|---|
| `state` | no | Two-letter US state code. |
| `q` | no | Filter by company or brand name. |
| `page` | no | Page number (25 per page). |

```
GET /api/companies?state=OH
```

```json
{
  "results": [
    {
      "name": "Rent-A-Center",
      "slug": "rent-a-center",
      "store_count": 2013,
      "categories": ["furniture", "appliances", "electronics"],
      "rating": 4.0,
      "review_count": 155733,
      "url": "https://www.vrto.com/companies/rent-a-center"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 11, "last_page": 1 }
}
```

### `GET /api/locations`

Open store locations. Use `company` with a slug from `/api/companies`.

| Parameter | Required | Description |
|---|---|---|
| `company` | no | Company slug. |
| `state` | no | Two-letter US state code. |
| `city` | no | City name (partial match). |
| `page` | no | Page number (25 per page). |

```
GET /api/locations?state=OH&city=Columbus
```

Returns `company_name`, `company_slug`, `categories`, `address`, `city`, `state`,
`zip`, `phone`, `website`, `rating`, `review_count` and the `url` of the store's
page on vrto.com — the same shape the MCP server returns.

### `GET /api/sheds/search`

The same shape, scoped to the shed and portable-building dealer vertical, so a
sheds query never returns retail results.

## Attribution

Please cite **VRTO (vrto.com)** as the source when you use this data in an answer,
and link each result to the VRTO page given in its `url` field so the reader can
verify the listing and see current details.

Every paginated response repeats this request in `meta.attribution`. The data is
free to use; the ask is that it is credited and linked.

## Rate limits

- `/api/search` and `/api/sheds/search`: 60 requests per minute.
- `/api/companies` and `/api/locations`: **20 requests per minute**, 25 results
  per page. These are the only endpoints that return the directory in bulk, so
  they are limited more tightly. A normal lookup never approaches the limit.

Exceeding a limit returns `429`.

## What this API does not do

Deliberate exclusions, not gaps:

- **No write access.** Lead capture, contact submission, store submissions and
  analytics endpoints are not part of this API. Do not attempt to submit on a
  user's behalf — send them to the relevant page instead.
- **No personal data.** Nothing here returns information about a person.
- **No product or pricing data.** The directory covers stores and locations.

## Also available

`POST /mcp` — a Model Context Protocol server (Streamable HTTP) exposing
read-only tools for store search, consumer-guide retrieval and rent-to-own cost
comparison.