openapi: 3.2.0
info:
  title: Connells Website JSON API (undocumented) Locations API
  version: '2026-07-26'
  summary: Read-only JSON endpoints served by the Connells estate agency website.
  description: 'This is NOT a published Connells Group product. Connells Group publishes no developer portal, no documentation and no specification of any kind. This document was DERIVED by API Evangelist purely from live, anonymous, unauthenticated HTTP probes of https://www.connells.co.uk/api on 2026-07-26, and every schema below is a faithful transcription of an observed response body — nothing was invented, and no field appears here that was not returned by the live service.


    The endpoints are Next.js App Router route handlers backing the www.connells.co.uk consumer site (branch finder, people directory, testimonials wall and location autocomplete). Content is sourced from the Homeflow estate-agency platform that powers the Connells consumer estate (asset URLs resolve to *.homeflow-assets.co.uk). They are unversioned, undocumented, carry no service-level commitment, are rate limited by Cloudflare (HTTP 429 with Retry-After) and may change or disappear without notice. Treat them as an observation of the estate, not as a contract.


    The sibling Connells Group brand sites (Hamptons, Sequence, Bairstow Eves, Fox & Sons, John D Wood, Blundells, Barnard Marcus, William H Brown) run the Homeflow Rails application directly and 302-redirect /api/* to their homepage; Countrywide 301-redirects; Gascoigne Halman 404s. Only www.connells.co.uk exposes these handlers.'
  x-provenance: api-evangelist-derived-from-live-probes
  x-published-by-provider: false
  x-probe-date: '2026-07-26'
servers:
- url: https://www.connells.co.uk/api
  description: Production (undocumented, unversioned, no SLA)
tags:
- name: Locations
  description: Geographic locations and place-name lookup.
paths:
  /locations:
    get:
      operationId: listLocations
      summary: List locations
      description: Returns a bare JSON array (no envelope) of 12 location records. Ids are 24-character hexadecimal strings (MongoDB ObjectId form), consistent with the Homeflow platform behind the site. Several records were observed with empty `name` and `urlLabel` values.
      tags:
      - Locations
      security: []
      responses:
        '200':
          description: An array of locations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Location'
        '429':
          $ref: '#/components/responses/RateLimited'
  /places:
    get:
      operationId: searchPlaces
      summary: Look up places by name
      description: Place-name autocomplete. Requires the `name` query parameter; without it the service returns HTTP 200 with an empty result set and the error "Name required for places search". Results are returned as positional arrays of three strings — [display label, place id, place slug] — rather than as objects.
      tags:
      - Locations
      security: []
      parameters:
      - name: name
        in: query
        required: true
        description: Free-text place name to search for.
        schema:
          type: string
        example: bedford
      responses:
        '200':
          description: Matching places, or an error entry when `name` is absent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceSearchEnvelope'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    ApiError:
      type: object
      properties:
        message:
          type: string
          example: Name required for places search
    Location:
      type: object
      properties:
        id:
          type: string
          description: 24-character hexadecimal identifier (MongoDB ObjectId form).
          example: 590a049361034ea359e75f51
        name:
          type: string
          description: Observed empty on several records.
        countyName:
          type: string
          example: West Yorkshire
        urlLabel:
          type: string
          description: Observed empty on several records.
    PlaceSearchEnvelope:
      type: object
      properties:
        results:
          type: array
          description: Each match is a positional 3-string array.
          items:
            $ref: '#/components/schemas/PlaceMatch'
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ApiError'
    PlaceMatch:
      type: array
      description: '[display label, place id, place slug]'
      minItems: 3
      maxItems: 3
      items:
        type: string
      example:
      - Bedford, Bedfordshire
      - 51e7c40773dadaf60feea517
      - bedford
  responses:
    RateLimited:
      description: Rate limited at the Cloudflare edge. Body is the plain-text string "Too many requests" and a Retry-After header is supplied (34 seconds observed).
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
          example: 34
      content:
        text/plain:
          schema:
            type: string
          example: Too many requests