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

# Places

> Returns the cities, city centres, suburbs and postcodes that match `q`, best first, as `{ places: [{ value, kind, states, detail, match }] }`. Every `value` is accepted by search `filters.locality` and matches at least one company. No authentication required — this is a free reference endpoint.



## OpenAPI

````yaml /openapi.json get /v1/places
openapi: 3.1.0
info:
  title: DataDingo API
  description: Company enrichment API.
  version: 1.0.0
  termsOfService: https://datadingo.com/terms
servers:
  - url: https://api.datadingo.com
security:
  - bearerAuth: []
paths:
  /v1/places:
    get:
      tags:
        - Reference
      summary: Places
      description: >-
        Returns the cities, city centres, suburbs and postcodes that match `q`,
        best first, as `{ places: [{ value, kind, states, detail, match }] }`.
        Every `value` is accepted by search `filters.locality` and matches at
        least one company. No authentication required — this is a free reference
        endpoint.
      parameters:
        - schema:
            maxLength: 100
            type: string
          in: query
          name: q
          required: false
          description: >-
            What the user typed: a city, suburb, "<city> CBD" or postcode.
            Spelling-tolerant (Mt/Mount, St/Saint). A trailing state ("Richmond
            VIC") only ranks. Digits search postcodes by prefix. Empty lists the
            capital cities.
        - schema:
            minimum: 1
            maximum: 50
            default: 20
            type: integer
          in: query
          name: limit
          required: false
          description: Most places to return.
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                  - places
                properties:
                  places:
                    type: array
                    items:
                      type: object
                      required:
                        - value
                        - kind
                        - states
                        - detail
                        - match
                      properties:
                        value:
                          description: >-
                            Send this as search filters.locality; it is also the
                            place's display name ("Greater Melbourne",
                            "Melbourne CBD", "Kew", "3000").
                          type: string
                        kind:
                          description: >-
                            How search reads `value`: a whole city area, a city
                            centre, one suburb, or one postcode.
                          anyOf:
                            - type: string
                              enum:
                                - city
                            - type: string
                              enum:
                                - cbd
                            - type: string
                              enum:
                                - suburb
                            - type: string
                              enum:
                                - postcode
                        states:
                          description: >-
                            The states it is served in, e.g. ["VIC"]. A suburb
                            name served in several states lists each.
                          type: array
                          items:
                            type: string
                        detail:
                          description: >-
                            A second line for a picker: "Melbourne and all its
                            suburbs" (a city), "Central suburb only", "Suburb",
                            "Postcode area · Melbourne".
                          type: string
                        match:
                          description: >-
                            How `q` matched: the same place ("exact"), the start
                            of its name ("prefix"), or the start of a later word
                            ("word").
                          anyOf:
                            - type: string
                              enum:
                                - exact
                            - type: string
                              enum:
                                - prefix
                            - type: string
                              enum:
                                - word
        '429':
          description: Rate limit exceeded, or today's free search results used up
          content:
            application/json:
              schema:
                description: Rate limit exceeded, or today's free search results used up
                type: object
                required:
                  - error
                  - message
                  - limit
                  - remaining
                  - resets_at
                properties:
                  error:
                    description: HTTP status code (429)
                    type: integer
                  message:
                    description: Human-readable error message
                    type: string
                  limit:
                    description: >-
                      The limit that was hit: requests allowed per minute, or
                      (on `POST /v1/company/search`) search results one user may
                      receive per UTC day
                    type: integer
                  remaining:
                    description: What is left of that limit (0)
                    type: integer
                  resets_at:
                    format: date-time
                    description: >-
                      ISO 8601 instant the limit resets (the next minute, or the
                      next UTC midnight for search results)
                    type: string
        '500':
          description: Standard error response
          content:
            application/json:
              schema:
                description: Standard error response
                type: object
                required:
                  - error
                  - message
                properties:
                  error:
                    description: HTTP status code
                    type: integer
                  message:
                    description: Human-readable error message
                    type: string
      security: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.