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

# Location Suggestions

> Autocomplete locations (cities, ZIPs, neighborhoods, addresses) for a partial query.

## Query Parameters

<ParamField query="query" type="string" required>
  Partial location to autocomplete (e.g. `austi`, `9021`, `toron`).
</ParamField>

<ParamField query="market" type="string" default="us">
  Which market to source suggestions from: `us` (realtor.com) or `ca` (realtor.ca).
</ParamField>

<ParamField query="limit" type="integer" default={10}>
  Maximum number of suggestions to return. Range: `1` - `25`.
</ParamField>

## Response

<ResponseField name="market" type="string">The market the suggestions came from.</ResponseField>
<ResponseField name="query" type="string">The query prefix that was autocompleted.</ResponseField>

<ResponseField name="suggestions" type="array">
  Array of suggestion objects.

  <Expandable title="Suggestion object">
    <ResponseField name="id" type="string">Suggestion id.</ResponseField>
    <ResponseField name="type" type="string">Suggestion type, e.g. `city`, `postal_code`, `neighborhood`, `address`.</ResponseField>
    <ResponseField name="label" type="string">Human-readable label, e.g. `Austin, TX`.</ResponseField>
    <ResponseField name="city" type="string">City (nullable).</ResponseField>
    <ResponseField name="state_code" type="string">State/province code (nullable).</ResponseField>
    <ResponseField name="postal_code" type="string">Postal/ZIP code (nullable).</ResponseField>
    <ResponseField name="country" type="string">ISO country code (nullable).</ResponseField>
    <ResponseField name="slug_id" type="string">Portal slug id (nullable).</ResponseField>
    <ResponseField name="geo_id" type="string">Portal geo id (nullable).</ResponseField>
    <ResponseField name="coordinate" type="object">Center coordinate `{lat, lon}` (nullable).</ResponseField>
    <ResponseField name="market" type="string">Market the suggestion belongs to.</ResponseField>
  </Expandable>
</ResponseField>

### Example Response

```json theme={null}
{
  "market": "us",
  "query": "austi",
  "suggestions": [
    {
      "id": "city:austin_tx",
      "type": "city",
      "label": "Austin, TX",
      "city": "Austin",
      "state_code": "TX",
      "postal_code": null,
      "country": "US",
      "slug_id": "Austin_TX",
      "geo_id": "1234",
      "coordinate": { "lat": 30.2672, "lon": -97.7431 },
      "market": "us"
    }
  ]
}
```

<Note>
  Each autocomplete request costs **2 credits**. Failed requests are not charged.
</Note>


## OpenAPI

````yaml GET /v1/realtor/autocomplete
openapi: 3.1.0
info:
  title: ScrapeBadger Realtor API
  version: 1.0.0
  description: >-
    Unified real-estate scraping API over realtor.com (US) and realtor.ca
    (Canada) for searching listings, fetching full property detail (price/tax
    history, schools, agents, estimates), location autocomplete, and reference
    data.
servers:
  - url: https://scrapebadger.com
    description: Production
security:
  - apiKeyAuth: []
paths:
  /v1/realtor/autocomplete:
    get:
      tags:
        - Realtor Search
      summary: Location Suggestions
      description: Return location autocomplete suggestions for a partial query.
      operationId: realtorAutocomplete
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
          description: Partial location prefix.
        - name: market
          in: query
          schema:
            type: string
            default: us
            enum:
              - us
              - ca
          description: Market to source suggestions from.
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 25
          description: Maximum number of suggestions (1-25).
      responses:
        '200':
          description: Suggestions
          content:
            application/json:
              schema:
                type: object
                properties:
                  market:
                    type: string
                  query:
                    type: string
                  suggestions:
                    type: array
                    items:
                      $ref: '#/components/schemas/Suggestion'
components:
  schemas:
    Suggestion:
      type: object
      properties:
        id:
          type:
            - string
            - 'null'
        type:
          type:
            - string
            - 'null'
        label:
          type:
            - string
            - 'null'
        city:
          type:
            - string
            - 'null'
        state_code:
          type:
            - string
            - 'null'
        postal_code:
          type:
            - string
            - 'null'
        country:
          type:
            - string
            - 'null'
        slug_id:
          type:
            - string
            - 'null'
        geo_id:
          type:
            - string
            - 'null'
        coordinate:
          $ref: '#/components/schemas/Coordinate'
        market:
          type:
            - string
            - 'null'
    Coordinate:
      type: object
      properties:
        lat:
          type:
            - number
            - 'null'
        lon:
          type:
            - number
            - 'null'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````