openapi: 3.0.0
info:
  title: Zillow Agents API
  description: |
    Search Zillow's directory of real estate agents and teams in a US city, ZIP code or neighborhood, or nationwide by agent, team or brokerage name.

    Each agent comes with their brokerage, Zillow profile link, photo, Top Agent badge, rating, review count, price range and sales, 15 agents a page. Team results report the sales of all team members.

    Filter by specialty, language, price range, Top Agent, buying, selling or Zillow Showcase. Zillow lists at most 25 pages of a search. Narrow a larger search with a ZIP code, a neighborhood or filters to reach more agents.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Zillow Agents Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine identifier
          schema:
            type: string
            enum: ["zillow_agents"]
            default: "zillow_agents"
        - name: q
          in: query
          required: false
          description: 'US location to find agents in: a city and state, ZIP code or neighborhood (e.g., "Seattle, WA", "98101", "Capitol Hill, Seattle, WA"). A state on its own returns the agents of its largest city, and counties and boroughs return no agents. Either q or name is required.'
          schema:
            type: string
            maxLength: 100
        - name: name
          in: query
          required: false
          description: Agent, team or brokerage name to search for. Without q, searches agents nationwide. Either q or name is required.
          schema:
            type: string
            maxLength: 100
        - name: specialty
          in: query
          required: false
          description: 'Comma-separated list of specialties. Returns agents who list every one of them. Supported values: first_time_home_buyers, investment_properties, rentals, military_or_veterans, luxury_homes, new_construction, property_management, senior_communities, relocation, foreclosure, lot_or_land, vacation_short_term_rentals.'
          schema:
            type: string
        - name: language
          in: query
          required: false
          description: 'Comma-separated list of languages. Returns agents who speak every one of them. Supported values: american_sign_language, arabic, bengali, cantonese, farsi, french, german, greek, haitian_creole, hebrew, hindi, hungarian, italian, japanese, korean, mandarin, polish, portuguese, russian, spanish, filipino, thai, turkish, ukrainian, vietnamese.'
          schema:
            type: string
        - name: is_top_agent
          in: query
          required: false
          description: Return only Zillow Top Agents.
          schema:
            type: boolean
            default: false
        - name: is_buying
          in: query
          required: false
          description: Return only agents who help buyers.
          schema:
            type: boolean
            default: false
        - name: is_selling
          in: query
          required: false
          description: Return only agents who help sellers.
          schema:
            type: boolean
            default: false
        - name: is_showcase_agent
          in: query
          required: false
          description: Return only agents who offer Zillow Showcase listings. This also limits the results to agents who help sellers, so it can't be combined with is_selling=false.
          schema:
            type: boolean
            default: false
        - name: price_min
          in: query
          required: false
          description: Lower end, in US dollars, of a price range. Returns agents whose price_range overlaps it. Takes the steps of Zillow's price slider.
          schema:
            type: integer
            enum: [0, 50000, 100000, 150000, 200000, 250000, 300000, 350000, 400000, 450000, 500000, 550000, 600000, 650000, 700000, 750000, 800000, 850000, 900000, 950000, 1000000, 1250000, 1500000, 1750000, 2000000, 2250000, 2500000, 2750000, 3000000, 3250000, 3500000, 3750000, 4000000, 4250000, 4500000, 4750000, 5000000, 6000000, 7000000, 8000000, 9000000, 10000000, 11000000, 12000000, 13000000, 14000000, 15000000, 16000000, 17000000, 18000000]
        - name: price_max
          in: query
          required: false
          description: Upper end, in US dollars, of the price range. Takes the same values as price_min and cannot be lower than it. Leave it out for no upper end.
          schema:
            type: integer
            enum: [0, 50000, 100000, 150000, 200000, 250000, 300000, 350000, 400000, 450000, 500000, 550000, 600000, 650000, 700000, 750000, 800000, 850000, 900000, 950000, 1000000, 1250000, 1500000, 1750000, 2000000, 2250000, 2500000, 2750000, 3000000, 3250000, 3500000, 3750000, 4000000, 4250000, 4500000, 4750000, 5000000, 6000000, 7000000, 8000000, 9000000, 10000000, 11000000, 12000000, 13000000, 14000000, 15000000, 16000000, 17000000, 18000000]
        - name: page
          in: query
          required: false
          description: Page of results, 15 agents a page. Zillow lists at most 25 pages.
          schema:
            type: integer
            minimum: 1
            maximum: 25
            default: 1
        - name: zero_retention
          in: query
          required: false
          description: Set to true to disable all logging and persistent storage. No request parameters, HTML, or JSON responses are stored or logged. Enterprise only.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        search_information:
          $ref: '#/components/schemas/SearchInformation'
        agents:
          type: array
          description: Agents and teams on this page, in Zillow's order.
          items:
            $ref: '#/components/schemas/Agent'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Message explaining why the search returned no agents, such as a location Zillow could not find.
    SearchMetadata:
      type: object
      required: [status, created_at]
      properties:
        id:
          type: string
          description: "Unique identifier for the search request"
        status:
          type: string
          description: "Status of the search request"
        created_at:
          type: string
          format: date-time
          description: "Timestamp when the search was created"
        request_time_taken:
          type: number
          description: "Time taken to make the request in seconds"
        parsing_time_taken:
          type: number
          description: "Time taken to parse the results in seconds"
        total_time_taken:
          type: number
          description: "Total time taken for the search in seconds"
        request_url:
          type: string
          description: "Zillow agent directory URL for this search"
        html_url:
          type: string
          description: "URL to view HTML results"
        json_url:
          type: string
          description: "URL to view JSON results"
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
        q:
          type: string
        name:
          type: string
        specialty:
          type: string
        language:
          type: string
        is_top_agent:
          type: boolean
        is_buying:
          type: boolean
        is_selling:
          type: boolean
        is_showcase_agent:
          type: boolean
        price_min:
          type: integer
        price_max:
          type: integer
        page:
          type: integer
        zero_retention:
          type: boolean
    SearchInformation:
      type: object
      required: [total_results]
      properties:
        total_results:
          type: integer
          description: Number of agents Zillow found for the search.
        location:
          type: string
          description: Location Zillow searched, as it names it.
        region:
          type: object
          description: Zillow region of the location searched.
          required: [id, type]
          properties:
            id:
              type: integer
              description: Zillow region identifier.
            type:
              type: string
              description: Type of the region, such as city, zipcode or neighborhood.
    Agent:
      type: object
      required: [position, agent_id, username, name, link, is_top_agent, is_team, reviews]
      properties:
        position:
          type: integer
          description: Position of the agent on this page, starting at 1.
        agent_id:
          type: string
          description: Zillow's encoded identifier of the agent or team.
        username:
          type: string
          description: Screen name of the agent's or team's Zillow profile.
        name:
          type: string
          description: Name of the agent or team.
        brokerage:
          type: string
          description: Brokerage the agent or team works with.
        link:
          type: string
          description: URL of the agent's or team's Zillow profile.
        thumbnail:
          type: string
          description: URL of the agent's or team's photo.
        logo:
          type: string
          description: URL of the brokerage or team logo.
        is_top_agent:
          type: boolean
          description: Whether Zillow marks the agent as a Top Agent.
        is_team:
          type: boolean
          description: Whether the result is a team, whose sales figures cover all team members.
        rating:
          type: number
          description: Average review rating out of 5.
        reviews:
          type: integer
          description: Number of reviews.
        price_range:
          type: string
          description: Price range of the homes the agent or team has sold, as Zillow displays it.
        sales_last_12_months:
          type: integer
          description: Number of homes the agent or team sold in the last 12 months.
        sales_in_location:
          type: integer
          description: Number of homes the agent or team has sold in the location searched.
    Pagination:
      type: object
      required: [current, total_pages]
      properties:
        current:
          type: integer
          description: Current page number.
        total_pages:
          type: integer
          description: Number of pages Zillow lists for the search, up to 25.
        next:
          type: string
          description: Zillow URL of the next page.
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
