> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwairy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Businesses

> Local business recommendations from AI responses

Access local business recommendations extracted from AI responses, primarily from Google AI Overview local results. Track which businesses AI platforms recommend for location-based queries.

## List Local Insights

<ParamField header="Authorization" type="string" required>
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

```http theme={null}
GET /api/v1/brands/{brandId}/local
```

### Path Parameters

<ParamField path="brandId" type="string" required>
  The unique identifier of the brand
</ParamField>

### Query Parameters

<ParamField query="period" type="number">
  Number of days to include. If not specified, returns all data.
</ParamField>

<ParamField query="startDate" type="string">
  Start date (ISO 8601 format)
</ParamField>

<ParamField query="endDate" type="string">
  End date (ISO 8601 format)
</ParamField>

<ParamField query="provider" type="string">
  Filter by AI provider. Supports comma-separated multi-select (e.g., `chatgpt,claude`).
</ParamField>

<ParamField query="category" type="string">
  Filter by business category (case-insensitive partial match)
</ParamField>

<ParamField query="limit" type="number" default="50">
  Maximum number of businesses to return (max: 100)
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of results to skip for pagination
</ParamField>

<ParamField query="sort" type="string" default="createdAt">
  Field to sort by: `createdAt`, `rating`, `reviewCount`, `position`, `businessName`
</ParamField>

<ParamField query="order" type="string" default="desc">
  Sort order: `asc` or `desc`
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination info">
    <ResponseField name="total" type="number">Total number of businesses matching filters</ResponseField>
    <ResponseField name="count" type="number">Number of businesses in this response</ResponseField>
    <ResponseField name="limit" type="number">Maximum items per page</ResponseField>
    <ResponseField name="offset" type="number">Number of items skipped</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="local" type="array">
  <Expandable title="Local business object">
    <ResponseField name="id" type="string">Local insight ID</ResponseField>
    <ResponseField name="businessName" type="string">Business name</ResponseField>
    <ResponseField name="category" type="string">Business category</ResponseField>
    <ResponseField name="address" type="string">Business address</ResponseField>
    <ResponseField name="websiteUrl" type="string">Business website URL</ResponseField>
    <ResponseField name="position" type="number">Position in the list (1 = top result)</ResponseField>
    <ResponseField name="rating" type="number">Business rating (0-5)</ResponseField>
    <ResponseField name="reviewCount" type="number">Number of reviews</ResponseField>
    <ResponseField name="prompt" type="string">Original prompt that triggered this result</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601 timestamp</ResponseField>
  </Expandable>
</ResponseField>

### Example Request

```bash theme={null}
curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/local?category=restaurant&limit=10" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

### Example Response

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 42,
    "count": 2,
    "limit": 10,
    "offset": 0
  },
  "local": [
    {
      "id": "loc1",
      "businessName": "La Maison Restaurant",
      "category": "French Restaurant",
      "address": "123 Main Street, Paris",
      "websiteUrl": "https://lamaison.fr",
      "position": 1,
      "rating": 4.8,
      "reviewCount": 2500,
      "prompt": "Best French restaurants in Paris",
      "createdAt": "2024-12-15T10:30:00Z"
    },
    {
      "id": "loc2",
      "businessName": "Café Central",
      "category": "Café",
      "address": "45 Avenue Montaigne, Paris",
      "websiteUrl": "https://cafecentral.fr",
      "position": 2,
      "rating": 4.5,
      "reviewCount": 1800,
      "prompt": "Best French restaurants in Paris",
      "createdAt": "2024-12-15T10:30:00Z"
    }
  ]
}
```

### Error Responses

| Status | Code              | Description                           |
| ------ | ----------------- | ------------------------------------- |
| 401    | `INVALID_TOKEN`   | Authentication failed                 |
| 404    | `BRAND_NOT_FOUND` | Brand doesn't exist or not accessible |