openapi: 3.0.0
paths:
  /:
    get:
      operationId: AppController_getHello
      parameters: []
      responses:
        '200':
          description: Return a welcome message and links to the API documentation.
      summary: Welcome to the Overture Maps API
      tags:
        - root
  /buildings:
    get:
      operationId: BuildingsController_getBuildings
      parameters:
        - name: lat
          required: true
          in: query
          description: Latitude coordinate. Required if country code is not provided.
          schema:
            example: 40.7128
            type: number
        - name: lng
          required: true
          in: query
          description: Longitude coordinate. Required if country code is not provided.
          schema:
            example: -74.006
            type: number
        - name: radius
          required: false
          in: query
          description: Search radius in meters, defaulting to 1000 meters if not provided.
          schema:
            minimum: 1
            default: 1000
            example: 1000
            type: number
        - name: limit
          required: false
          in: query
          description: >-
            Limit on the number of results returned, defaulting to 1000 if not
            provided.
          schema:
            minimum: 1
            default: 1000
            example: 10
            type: number
        - name: page
          required: false
          in: query
          description: >-
            Page number for pagination (0-indexed), used together with `limit`
            as the page size. Responses include Pagination-Count (total matching
            results), Pagination-Page and Pagination-Limit headers. Defaults to
            0.
          schema:
            minimum: 0
            default: 0
            example: 0
            type: number
        - name: format
          required: false
          in: query
          description: >-
            Response format, defaulting to JSON. Options are "json", "csv", or
            "geojson".
          schema:
            default: json
            example: json
            enum:
              - json
              - csv
              - geojson
            type: string
        - name: includes
          required: false
          in: query
          description: >-
            Array of fields to include in the properties field of the response,
            provided as a comma-separated string. Any fields not in the list
            will be excluded from the properties object. This is used to make
            the response lighter so your application is faster.
          schema:
            example:
              - id
              - geometry
              - properties
            type: array
            items:
              type: string
        - name: country
          required: false
          in: query
          description: >-
            ISO 3166 country code consisting of 2 characters. Required if
            lat/lng are not provided.
          schema:
            example: US
            type: string
      responses:
        '200':
          description: ''
      security:
        - API_KEY: []
      tags:
        - Buildings
  /places:
    get:
      operationId: PlacesController_
      parameters:
        - description: Latitude coordinate. Required if country code is not provided.
          name: lat
          in: query
          required: true
          schema:
            example: 40.7128
        - description: Longitude coordinate. Required if country code is not provided.
          name: lng
          in: query
          required: true
          schema:
            example: -74.006
        - description: Search radius in meters, defaulting to 1000 meters if not provided.
          required: false
          name: radius
          in: query
          schema:
            minimum: 1
            default: 1000
            example: 1000
        - description: >-
            Limit on the number of results returned, defaulting to 1000 if not
            provided.
          required: false
          name: limit
          in: query
          schema:
            minimum: 1
            default: 1000
            example: 10
        - description: >-
            Page number for pagination (0-indexed), used together with `limit`
            as the page size. Responses include Pagination-Count (total matching
            results), Pagination-Page and Pagination-Limit headers. Defaults to
            0.
          required: false
          name: page
          in: query
          schema:
            minimum: 0
            default: 0
            example: 0
        - description: >-
            Response format, defaulting to JSON. Options are "json", "csv", or
            "geojson".
          required: false
          name: format
          in: query
          schema:
            default: json
            example: json
        - description: >-
            Array of fields to include in the properties field of the response,
            provided as a comma-separated string. Any fields not in the list
            will be excluded from the properties object. This is used to make
            the response lighter so your application is faster.
          required: false
          name: includes
          in: query
          schema:
            example:
              - id
              - geometry
              - properties
        - description: >-
            ISO 3166 country code consisting of 2 characters. Required if
            lat/lng are not provided.
          required: false
          name: country
          in: query
          schema:
            example: US
        - description: >-
            Filter places to only those with a source dataset matching this
            value.
          required: false
          name: source
          in: query
          schema:
            example: meta
        - description: Wikidata brand ID associated with the place.
          required: false
          name: brand_wikidata
          in: query
          schema:
            example: Q12345
        - description: Brand name associated with the place.
          required: false
          name: brand_name
          in: query
          schema:
            example: Starbucks
        - description: >-
            Minimum confidence score for the places to be returned, defaulting
            to 0.5 if not provided.
          required: false
          name: min_confidence
          in: query
          schema:
            default: 0.5
            example: 0.5
        - description: >-
            Array of category names, provided as a comma-separated string.
            Matches the legacy Overture categories vocabulary and the newer
            taxonomy/basic_category vocabulary.
          required: false
          name: categories
          in: query
          schema:
            example: food,retail
        - description: >-
            Array of Overture taxonomy categories, provided as a comma-separated
            string. Matches the primary category or any ancestor in the taxonomy
            hierarchy, so e.g. "food_and_drink" matches every descendant
            category.
          required: false
          name: taxonomy
          in: query
          schema:
            example: food_and_drink
        - description: >-
            Filter by operating status, e.g. "open" or "permanently_closed".
            Places without signals have a null operating status and are excluded
            when this filter is used.
          required: false
          name: operating_status
          in: query
          schema:
            example: open
        - description: >-
            Comma-separated list of enrichment fields to include. Use "brand"
            for Wikidata-sourced brand details (logo, website, industry, parent)
            on branded places.
          required: false
          name: enrichment_fields
          in: query
          schema:
            example: brand
        - description: >-
            Return only places that already have at least one of the listed
            contact fields. Comma-separated, matched with OR: e.g. "website"
            returns places with a website; "website,social" returns places with
            a website OR a social link. Useful for filtering to businesses you
            can verify. Allowed values: website, phone, email, social.
          required: false
          name: has_contact
          in: query
          schema:
            example: website,social
      responses:
        '200':
          description: Return Places.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlaceResponseDto'
      security:
        - API_KEY: []
      summary: Get Places using Query params as filters
      tags:
        - Places
  /places/buildings:
    get:
      operationId: PlacesController_
      parameters:
        - description: Latitude coordinate. Required if country code is not provided.
          name: lat
          in: query
          required: true
          schema:
            example: 40.7128
        - description: Longitude coordinate. Required if country code is not provided.
          name: lng
          in: query
          required: true
          schema:
            example: -74.006
        - description: Search radius in meters, defaulting to 1000 meters if not provided.
          required: false
          name: radius
          in: query
          schema:
            minimum: 1
            default: 1000
            example: 1000
        - description: >-
            Limit on the number of results returned, defaulting to 1000 if not
            provided.
          required: false
          name: limit
          in: query
          schema:
            minimum: 1
            default: 1000
            example: 10
        - description: >-
            Page number for pagination (0-indexed), used together with `limit`
            as the page size. Responses include Pagination-Count (total matching
            results), Pagination-Page and Pagination-Limit headers. Defaults to
            0.
          required: false
          name: page
          in: query
          schema:
            minimum: 0
            default: 0
            example: 0
        - description: >-
            Response format, defaulting to JSON. Options are "json", "csv", or
            "geojson".
          required: false
          name: format
          in: query
          schema:
            default: json
            example: json
        - description: >-
            Array of fields to include in the properties field of the response,
            provided as a comma-separated string. Any fields not in the list
            will be excluded from the properties object. This is used to make
            the response lighter so your application is faster.
          required: false
          name: includes
          in: query
          schema:
            example:
              - id
              - geometry
              - properties
        - description: >-
            ISO 3166 country code consisting of 2 characters. Required if
            lat/lng are not provided.
          required: false
          name: country
          in: query
          schema:
            example: US
        - description: >-
            Filter places to only those with a source dataset matching this
            value.
          required: false
          name: source
          in: query
          schema:
            example: meta
        - description: Wikidata brand ID associated with the place.
          required: false
          name: brand_wikidata
          in: query
          schema:
            example: Q12345
        - description: Brand name associated with the place.
          required: false
          name: brand_name
          in: query
          schema:
            example: Starbucks
        - description: >-
            Minimum confidence score for the places to be returned, defaulting
            to 0.5 if not provided.
          required: false
          name: min_confidence
          in: query
          schema:
            default: 0.5
            example: 0.5
        - description: >-
            Array of category names, provided as a comma-separated string.
            Matches the legacy Overture categories vocabulary and the newer
            taxonomy/basic_category vocabulary.
          required: false
          name: categories
          in: query
          schema:
            example: food,retail
        - description: >-
            Array of Overture taxonomy categories, provided as a comma-separated
            string. Matches the primary category or any ancestor in the taxonomy
            hierarchy, so e.g. "food_and_drink" matches every descendant
            category.
          required: false
          name: taxonomy
          in: query
          schema:
            example: food_and_drink
        - description: >-
            Filter by operating status, e.g. "open" or "permanently_closed".
            Places without signals have a null operating status and are excluded
            when this filter is used.
          required: false
          name: operating_status
          in: query
          schema:
            example: open
        - description: >-
            Comma-separated list of enrichment fields to include. Use "brand"
            for Wikidata-sourced brand details (logo, website, industry, parent)
            on branded places.
          required: false
          name: enrichment_fields
          in: query
          schema:
            example: brand
        - description: >-
            Return only places that already have at least one of the listed
            contact fields. Comma-separated, matched with OR: e.g. "website"
            returns places with a website; "website,social" returns places with
            a website OR a social link. Useful for filtering to businesses you
            can verify. Allowed values: website, phone, email, social.
          required: false
          name: has_contact
          in: query
          schema:
            example: website,social
      responses:
        '200':
          description: Return Places with Buildings.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlaceResponseDto'
      security:
        - API_KEY: []
      summary: Get Places with their Building shapes using Query params as filters
      tags:
        - Places
  /places/brands:
    get:
      operationId: PlacesController_
      parameters:
        - description: Latitude coordinate. Required if country code is not provided.
          name: lat
          in: query
          required: true
          schema:
            example: 40.7128
        - description: Longitude coordinate. Required if country code is not provided.
          name: lng
          in: query
          required: true
          schema:
            example: -74.006
        - description: Search radius in meters, defaulting to 1000 meters if not provided.
          required: false
          name: radius
          in: query
          schema:
            minimum: 1
            default: 1000
            example: 1000
        - description: >-
            Limit on the number of results returned, defaulting to 1000 if not
            provided.
          required: false
          name: limit
          in: query
          schema:
            minimum: 1
            default: 1000
            example: 10
        - description: >-
            Page number for pagination (0-indexed), used together with `limit`
            as the page size. Responses include Pagination-Count (total matching
            results), Pagination-Page and Pagination-Limit headers. Defaults to
            0.
          required: false
          name: page
          in: query
          schema:
            minimum: 0
            default: 0
            example: 0
        - description: >-
            Response format, defaulting to JSON. Options are "json", "csv", or
            "geojson".
          required: false
          name: format
          in: query
          schema:
            default: json
            example: json
        - description: >-
            Array of fields to include in the properties field of the response,
            provided as a comma-separated string. Any fields not in the list
            will be excluded from the properties object. This is used to make
            the response lighter so your application is faster.
          required: false
          name: includes
          in: query
          schema:
            example:
              - id
              - geometry
              - properties
        - description: >-
            ISO 3166 country code consisting of 2 characters. Required if
            lat/lng are not provided.
          required: false
          name: country
          in: query
          schema:
            example: US
        - description: Array of category names, provided as a comma-separated string.
          required: false
          name: categories
          in: query
          schema:
            example:
              - food
              - retail
      responses:
        '200':
          description: Return all Brands, along with a count of all Places for each.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BrandDto'
      security:
        - API_KEY: []
      summary: Get all Brands from Places using Query params as filters
      tags:
        - Places
  /places/countries:
    get:
      operationId: PlacesController_
      parameters: []
      responses:
        '200':
          description: >-
            Return all Countries, as well as a count of all the Places and
            Brands in each.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CountryResponseDto'
      security:
        - API_KEY: []
      summary: Get all Countries from Places using Query params as filters
      tags:
        - Places
  /places/categories:
    get:
      operationId: PlacesController_
      parameters:
        - description: Latitude coordinate. Required if country code is not provided.
          name: lat
          in: query
          required: true
          schema:
            example: 40.7128
        - description: Longitude coordinate. Required if country code is not provided.
          name: lng
          in: query
          required: true
          schema:
            example: -74.006
        - description: Search radius in meters, defaulting to 1000 meters if not provided.
          required: false
          name: radius
          in: query
          schema:
            minimum: 1
            default: 1000
            example: 1000
        - description: >-
            Limit on the number of results returned, defaulting to 1000 if not
            provided.
          required: false
          name: limit
          in: query
          schema:
            minimum: 1
            default: 1000
            example: 10
        - description: >-
            Page number for pagination (0-indexed), used together with `limit`
            as the page size. Responses include Pagination-Count (total matching
            results), Pagination-Page and Pagination-Limit headers. Defaults to
            0.
          required: false
          name: page
          in: query
          schema:
            minimum: 0
            default: 0
            example: 0
        - description: >-
            Response format, defaulting to JSON. Options are "json", "csv", or
            "geojson".
          required: false
          name: format
          in: query
          schema:
            default: json
            example: json
        - description: >-
            Array of fields to include in the properties field of the response,
            provided as a comma-separated string. Any fields not in the list
            will be excluded from the properties object. This is used to make
            the response lighter so your application is faster.
          required: false
          name: includes
          in: query
          schema:
            example:
              - id
              - geometry
              - properties
        - description: ISO 3166 country code consisting of 2 characters.
          required: false
          name: country
          in: query
          schema:
            minLength: 2
            maxLength: 2
            example: US
      responses:
        '200':
          description: >-
            Return all Categories, along with a count of all Brands and Places
            for each
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryResponseDto'
      security:
        - API_KEY: []
      summary: Get all Categories from Places using Query params as filters
      tags:
        - Places
  /addresses:
    get:
      operationId: AddressesController_getAddresses
      parameters:
        - name: lat
          required: true
          in: query
          description: Latitude coordinate. Required if country code is not provided.
          schema:
            example: 40.7128
            type: number
        - name: lng
          required: true
          in: query
          description: Longitude coordinate. Required if country code is not provided.
          schema:
            example: -74.006
            type: number
        - name: radius
          required: false
          in: query
          description: Search radius in meters, defaulting to 1000 meters if not provided.
          schema:
            minimum: 1
            default: 1000
            example: 1000
            type: number
        - name: limit
          required: false
          in: query
          description: >-
            Limit on the number of results returned, defaulting to 1000 if not
            provided.
          schema:
            minimum: 1
            default: 1000
            example: 10
            type: number
        - name: page
          required: false
          in: query
          description: >-
            Page number for pagination (0-indexed), used together with `limit`
            as the page size. Responses include Pagination-Count (total matching
            results), Pagination-Page and Pagination-Limit headers. Defaults to
            0.
          schema:
            minimum: 0
            default: 0
            example: 0
            type: number
        - name: format
          required: false
          in: query
          description: >-
            Response format, defaulting to JSON. Options are "json", "csv", or
            "geojson".
          schema:
            default: json
            example: json
            enum:
              - json
              - csv
              - geojson
            type: string
        - name: includes
          required: false
          in: query
          description: >-
            Array of fields to include in the properties field of the response,
            provided as a comma-separated string. Any fields not in the list
            will be excluded from the properties object. This is used to make
            the response lighter so your application is faster.
          schema:
            example:
              - id
              - geometry
              - properties
            type: array
            items:
              type: string
        - name: country
          required: false
          in: query
          description: >-
            ISO 3166 country code consisting of 2 characters. Required if
            lat/lng are not provided.
          schema:
            example: US
            type: string
      responses:
        '200':
          description: Return Addresses.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AddressDto'
      security:
        - API_KEY: []
      summary: Get Addresses using Query params as filters
      tags:
        - Addresses
  /base:
    get:
      operationId: BaseController_getBaseFeatures
      parameters:
        - name: lat
          required: true
          in: query
          description: Latitude coordinate. Required if country code is not provided.
          schema:
            example: 40.7128
            type: number
        - name: lng
          required: true
          in: query
          description: Longitude coordinate. Required if country code is not provided.
          schema:
            example: -74.006
            type: number
        - name: radius
          required: false
          in: query
          description: Search radius in meters, defaulting to 1000 meters if not provided.
          schema:
            minimum: 1
            default: 1000
            example: 1000
            type: number
        - name: limit
          required: false
          in: query
          description: >-
            Limit on the number of results returned, defaulting to 1000 if not
            provided.
          schema:
            minimum: 1
            default: 1000
            example: 10
            type: number
        - name: page
          required: false
          in: query
          description: >-
            Page number for pagination (0-indexed), used together with `limit`
            as the page size. Responses include Pagination-Count (total matching
            results), Pagination-Page and Pagination-Limit headers. Defaults to
            0.
          schema:
            minimum: 0
            default: 0
            example: 0
            type: number
        - name: format
          required: false
          in: query
          description: >-
            Response format, defaulting to JSON. Options are "json", "csv", or
            "geojson".
          schema:
            default: json
            example: json
            enum:
              - json
              - csv
              - geojson
            type: string
        - name: includes
          required: false
          in: query
          description: >-
            Array of fields to include in the properties field of the response,
            provided as a comma-separated string. Any fields not in the list
            will be excluded from the properties object. This is used to make
            the response lighter so your application is faster.
          schema:
            example:
              - id
              - geometry
              - properties
            type: array
            items:
              type: string
        - name: country
          required: false
          in: query
          description: >-
            ISO 3166 country code consisting of 2 characters. Required if
            lat/lng are not provided.
          schema:
            example: US
            type: string
      responses:
        '200':
          description: Return Base features.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BaseDto'
      security:
        - API_KEY: []
      summary: Get Base features using Query params as filters
      tags:
        - Base
  /transportation:
    get:
      operationId: TransportationController_getTransportationSegments
      parameters:
        - name: lat
          required: true
          in: query
          description: Latitude coordinate. Required if country code is not provided.
          schema:
            example: 40.7128
            type: number
        - name: lng
          required: true
          in: query
          description: Longitude coordinate. Required if country code is not provided.
          schema:
            example: -74.006
            type: number
        - name: radius
          required: false
          in: query
          description: Search radius in meters, defaulting to 1000 meters if not provided.
          schema:
            minimum: 1
            default: 1000
            example: 1000
            type: number
        - name: limit
          required: false
          in: query
          description: >-
            Limit on the number of results returned, defaulting to 1000 if not
            provided.
          schema:
            minimum: 1
            default: 1000
            example: 10
            type: number
        - name: page
          required: false
          in: query
          description: >-
            Page number for pagination (0-indexed), used together with `limit`
            as the page size. Responses include Pagination-Count (total matching
            results), Pagination-Page and Pagination-Limit headers. Defaults to
            0.
          schema:
            minimum: 0
            default: 0
            example: 0
            type: number
        - name: format
          required: false
          in: query
          description: >-
            Response format, defaulting to JSON. Options are "json", "csv", or
            "geojson".
          schema:
            default: json
            example: json
            enum:
              - json
              - csv
              - geojson
            type: string
        - name: includes
          required: false
          in: query
          description: >-
            Array of fields to include in the properties field of the response,
            provided as a comma-separated string. Any fields not in the list
            will be excluded from the properties object. This is used to make
            the response lighter so your application is faster.
          schema:
            example:
              - id
              - geometry
              - properties
            type: array
            items:
              type: string
        - name: country
          required: false
          in: query
          description: >-
            ISO 3166 country code consisting of 2 characters. Required if
            lat/lng are not provided.
          schema:
            example: US
            type: string
      responses:
        '200':
          description: Return Transportation segments.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TransportationDto'
      security:
        - API_KEY: []
      summary: Get Transportation segments using Query params as filters
      tags:
        - Transportation
  /divisions:
    get:
      operationId: DivisionsController_getDivisions
      parameters:
        - name: lat
          required: false
          in: query
          description: >-
            Latitude coordinate. Required if no country, name or bbox filter is
            provided.
          schema:
            example: 40.7128
            type: number
        - name: lng
          required: false
          in: query
          description: >-
            Longitude coordinate. Required if no country, name or bbox filter is
            provided.
          schema:
            example: -74.006
            type: number
        - name: radius
          required: false
          in: query
          description: Search radius in meters, defaulting to 1000 meters if not provided.
          schema:
            minimum: 1
            default: 1000
            example: 1000
            type: number
        - name: limit
          required: false
          in: query
          description: >-
            Limit on the number of results returned, defaulting to 1000 if not
            provided.
          schema:
            minimum: 1
            default: 1000
            example: 10
            type: number
        - name: page
          required: false
          in: query
          description: >-
            Page number for pagination (0-indexed), used together with `limit`
            as the page size. Responses include Pagination-Count (total matching
            results), Pagination-Page and Pagination-Limit headers. Defaults to
            0.
          schema:
            minimum: 0
            default: 0
            example: 0
            type: number
        - name: format
          required: false
          in: query
          description: >-
            Response format, defaulting to JSON. Options are "json", "csv", or
            "geojson".
          schema:
            default: json
            example: json
            enum:
              - json
              - csv
              - geojson
            type: string
        - name: includes
          required: false
          in: query
          description: >-
            Array of fields to include in the properties field of the response,
            provided as a comma-separated string. Any fields not in the list
            will be excluded from the properties object. This is used to make
            the response lighter so your application is faster.
          schema:
            example:
              - id
              - geometry
              - properties
            type: array
            items:
              type: string
        - name: country
          required: false
          in: query
          description: >-
            ISO 3166 country code consisting of 2 characters. Required if
            lat/lng are not provided.
          schema:
            example: US
            type: string
        - name: name
          required: false
          in: query
          description: >-
            Case-insensitive substring match against the division primary name
            and English common name. Also matches an exact division ID.
          schema:
            example: westminster
            type: string
        - name: subtype
          required: false
          in: query
          description: >-
            Filter by division subtype, provided as a comma-separated list (e.g.
            "county,locality").
          schema:
            example: county,locality
            type: array
            items:
              type: string
        - name: admin_level
          required: false
          in: query
          description: >-
            Filter by admin_level — the division's position in its country's
            hierarchy (0 = country). Provided as a comma-separated list (e.g.
            "1,2").
          schema:
            example: '2'
            type: string
        - name: bbox
          required: false
          in: query
          description: >-
            Bounding box filter as "xmin,ymin,xmax,ymax" (lng/lat order).
            Returns divisions whose bounding box intersects it.
          schema:
            example: '-74.3,40.5,-73.7,40.9'
            type: string
        - name: include_geometry
          required: false
          in: query
          description: >-
            Whether to include the full polygon geometry in each result.
            Defaults to false for name searches (fetch geometry via GET
            /divisions/{id}) and true otherwise. Division polygons can be
            megabytes each, so leave this off for search boxes.
          schema:
            example: false
            type: boolean
      responses:
        '200':
          description: Return Division areas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DivisionDto'
      security:
        - API_KEY: []
      summary: Get Division areas using Query params as filters
      tags:
        - Divisions
  /divisions/{id}:
    get:
      operationId: DivisionsController_getDivisionById
      parameters:
        - name: id
          required: true
          in: path
          description: Overture division area ID
          schema:
            example: 0850b45bffffffff01c3320da9d5f43d
            type: string
      responses:
        '200':
          description: Return the Division area.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DivisionDto'
        '404':
          description: Division area not found.
      security:
        - API_KEY: []
      summary: Get a single Division area by ID, including its full polygon geometry
      tags:
        - Divisions
info:
  title: Overture Maps API Documentation
  description: OpenAPI docs for the Overture Maps API
  version: '1.0'
  contact:
    name: Aden Forshaw
    url: https://thatapicompany.com/overture-maps-api
    email: aden@thatapicompany.com
tags:
  - name: places
    description: Operations related to Places
servers:
  - url: http://localhost:8080/
    description: Local environment
  - url: https://api.overturemapsapi.com
    description: Cloud API Service
components:
  securitySchemes:
    API_KEY:
      type: apiKey
      in: header
      name: x-api-key
  schemas:
    GeometryDto:
      type: object
      properties:
        type:
          type: string
          description: Type of geometry
          example: Point
        coordinates:
          description: Coordinates representing the geometry.
          example:
            - 40.7128
            - -74.006
          type: array
          items:
            type: number
      required:
        - type
        - coordinates
    CategoryDto:
      type: object
      properties:
        primary:
          type: string
          description: Primary category of the place.
          example: Retail
      required:
        - primary
    TaxonomyDto:
      type: object
      properties:
        primary:
          type: string
          description: Primary taxonomy category of the place.
          example: accountant
        hierarchy:
          description: >-
            Full taxonomy hierarchy path from the top-level category to the
            primary category.
          example:
            - services_and_business
            - financial_service
            - accountant
          type: array
          items:
            type: string
        alternates:
          description: Alternate taxonomy categories for the place.
          type: array
          items:
            type: string
    BrandRulesDto:
      type: object
      properties:
        variant:
          type: string
          description: Variant of the rule.
          example: Abbreviation
        value:
          type: string
          description: Value associated with the rule.
          example: CP
      required:
        - variant
        - value
    BrandNamesDto:
      type: object
      properties:
        primary:
          type: string
          description: Primary name of the place.
          example: Central Park
        common:
          type: object
          description: Common names in different languages.
          example:
            en: Central Park
            es: Parque Central
          properties: {}
        rules:
          description: Naming rules or variants associated with the place.
          type: array
          items:
            $ref: '#/components/schemas/BrandRulesDto'
      required:
        - primary
    BrandDto:
      type: object
      properties:
        names:
          description: Names associated with the brand, usually Primary is the most useful
          allOf:
            - $ref: '#/components/schemas/BrandNamesDto'
        wikidata:
          type: string
          description: Wikidata QID of the brand.
          example: Q37158
        ext_logo_url:
          type: string
          description: >-
            Brand logo URL (Wikimedia Commons, resizable with ?width=N). Sourced
            from Wikidata (CC0).
          example: >-
            http://commons.wikimedia.org/wiki/Special:FilePath/Starbucks%20coffee%20wordmark.png
        ext_website:
          type: string
          description: Official brand website. Sourced from Wikidata (CC0).
          example: https://www.starbucks.com/
        ext_industry:
          type: string
          description: Industry of the brand. Sourced from Wikidata (CC0).
          example: coffee industry
        ext_parent:
          type: string
          description: Parent organisation of the brand. Sourced from Wikidata (CC0).
          example: Starbucks Corporation
        ext_wikidata_label:
          type: string
          description: English label of the brand on Wikidata (CC0).
          example: Starbucks
      required:
        - names
    AddressDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the address.
          example: '12345'
        type:
          type: string
          description: Type of place or feature.
          example: Address
        geometry:
          description: Geometric representation of the address.
          allOf:
            - $ref: '#/components/schemas/GeometryDto'
        properties:
          description: Properties and additional details.
          allOf:
            - $ref: '#/components/schemas/AddressPropertiesDto'
      required:
        - id
        - type
        - geometry
        - properties
    SourceDto:
      type: object
      properties:
        property:
          type: string
          description: Source property name.
          example: OpenStreetMap
        dataset:
          type: string
          description: Dataset source for the place.
          example: OSM
        record_id:
          type: string
          description: Unique identifier for the record in the dataset.
          example: osm12345
        license:
          type: string
          description: License of the source data.
          example: CDLA-Permissive-2.0
      required:
        - property
        - dataset
        - record_id
    RulesDto:
      type: object
      properties:
        variant:
          type: string
          description: Variant of the rule.
          example: Abbreviation
        value:
          type: string
          description: Value associated with the rule.
          example: CP
      required:
        - variant
        - value
    PlaceNamesDto:
      type: object
      properties:
        primary:
          type: string
          description: Primary name of the place.
          example: Central Park
        common:
          type: object
          description: Common names in different languages.
          example:
            en: Central Park
            es: Parque Central
          properties: {}
        rules:
          description: Naming rules or variants associated with the place.
          type: array
          items:
            $ref: '#/components/schemas/RulesDto'
      required:
        - primary
    PlacePropertiesDto:
      type: object
      properties:
        categories:
          description: Primary category of the place.
          allOf:
            - $ref: '#/components/schemas/CategoryDto'
        basic_category:
          type: string
          description: >-
            Basic category of the place from the Overture taxonomy (schema
            v1.15+).
          example: financial_service
        taxonomy:
          description: >-
            Overture places taxonomy classification (schema v1.15+). Replaces
            `categories` upstream from September 2026; both are provided here.
          allOf:
            - $ref: '#/components/schemas/TaxonomyDto'
        operating_status:
          type: string
          description: >-
            Operating status of the place, e.g. "open" or "permanently_closed".
            Null when no signals are present.
          example: open
        confidence:
          type: number
          description: Confidence score of the place.
          example: 0.8
        websites:
          description: Websites associated with the place.
          type: array
          items:
            type: string
        emails:
          description: Emails associated with the place.
          type: array
          items:
            type: string
        socials:
          description: Social media links associated with the place.
          type: array
          items:
            type: string
        phones:
          description: Phone numbers associated with the place.
          type: array
          items:
            type: string
        brand:
          description: Brand details if applicable.
          allOf:
            - $ref: '#/components/schemas/BrandDto'
        addresses:
          description: Address information of the place.
          type: array
          items:
            $ref: '#/components/schemas/AddressDto'
        theme:
          type: string
          description: Theme associated with the place.
          example: Restaurant
        type:
          type: string
          description: Type of feature or place.
          example: Commercial
        version:
          type: string
          description: Version number of the place data.
          example: '1'
        sources:
          description: Source information for the place data.
          type: array
          items:
            $ref: '#/components/schemas/SourceDto'
        names:
          description: Name details for the place.
          allOf:
            - $ref: '#/components/schemas/PlaceNamesDto'
        ext_name:
          description: Name of the place.
          allOf:
            - $ref: '#/components/schemas/PlaceNamesDto'
        ext_brand:
          type: object
          description: >-
            Wikidata-sourced brand details (CC0). Present when enrichment_fields
            includes "brand" and the place has a brand with a Wikidata QID.
      required:
        - categories
        - theme
        - type
        - version
        - sources
        - names
        - ext_name
    PlaceEnrichmentDto:
      type: object
      properties:
        source:
          type: string
          enum:
            - hosted
        fields:
          type: object
      required:
        - source
        - fields
    PlaceResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the place.
          example: '12345'
        type:
          type: string
          description: Type of place or feature.
          example: Point of Interest
        geometry:
          description: Geometric representation of the place.
          allOf:
            - $ref: '#/components/schemas/GeometryDto'
        properties:
          description: Properties and additional details of the place.
          allOf:
            - $ref: '#/components/schemas/PlacePropertiesDto'
        enrichment:
          description: Hosted enrichment data.
          allOf:
            - $ref: '#/components/schemas/PlaceEnrichmentDto'
      required:
        - id
        - type
        - geometry
        - properties
    CountryCountsDto:
      type: object
      properties:
        places:
          type: number
          description: Number of places in this Country
          example: 100
        brands:
          type: number
          description: Number of brands that are associated with the Country
          example: 10
      required:
        - places
        - brands
    CountryResponseDto:
      type: object
      properties:
        country:
          type: string
          description: The ISO code of the Country.
          example: US
        ext_counts:
          description: >-
            Counts related to the Country e.g. how many Places and Brands are
            associated with it
          allOf:
            - $ref: '#/components/schemas/CountryCountsDto'
      required:
        - country
        - ext_counts
    CategoryCountsDto:
      type: object
      properties:
        places:
          type: number
          description: Number of places with this Category
          example: 100
        brands:
          type: number
          description: Number of brands that are associated with the Categorys
          example: 10
      required:
        - places
        - brands
    CategoryResponseDto:
      type: object
      properties:
        primary:
          type: string
          description: Primary category of the place.
          example: Retail
        ext_counts:
          description: >-
            Counts related to the Category e.g. how many Places and Brands are
            associated with it
          allOf:
            - $ref: '#/components/schemas/CategoryCountsDto'
      required:
        - primary
        - ext_counts
    AddressPropertiesDto:
      type: object
      properties:
        country:
          type: string
          description: Country
        postcode:
          type: string
          description: Postcode
        street:
          type: string
          description: Street name
        number:
          type: string
          description: Street number
        unit:
          type: string
          description: Unit number
        address_levels:
          description: Address levels (e.g., state, city)
          type: array
          items:
            type: string
        postal_city:
          type: string
          description: Postal city
    BasePropertiesDto:
      type: object
      properties:
        subtype:
          type: string
          description: Subtype of the feature
        class:
          type: string
          description: Class of the feature
    BaseDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the base feature.
          example: '12345'
        type:
          type: string
          description: Type of feature.
          example: landUse
        geometry:
          description: Geometric representation of the base feature.
          allOf:
            - $ref: '#/components/schemas/GeometryDto'
        properties:
          description: Properties and additional details.
          allOf:
            - $ref: '#/components/schemas/BasePropertiesDto'
      required:
        - id
        - type
        - geometry
        - properties
    TransportationPropertiesDto:
      type: object
      properties:
        subtype:
          type: string
          description: Subtype of the segment
        class:
          type: string
          description: Class of the segment
        subclass:
          type: string
          description: Subclass of the segment
        names:
          type: object
          description: Names associated with the segment
        connectors:
          description: List of connectors
          type: array
          items:
            type: string
        routes:
          description: Routes
          type: array
          items:
            type: string
        subclass_rules:
          description: Subclass rules
          type: array
          items:
            type: string
        access_restrictions:
          description: Access restrictions
          type: array
          items:
            type: string
        level_rules:
          description: Level rules
          type: array
          items:
            type: string
        destinations:
          description: Destinations
          type: array
          items:
            type: string
        prohibited_transitions:
          description: Prohibited transitions
          type: array
          items:
            type: string
        road_surface:
          description: Road surface
          type: array
          items:
            type: string
        road_flags:
          description: Road flags
          type: array
          items:
            type: string
        speed_limits:
          description: Speed limits
          type: array
          items:
            type: string
        width_rules:
          description: Width rules
          type: array
          items:
            type: string
        rail_flags:
          description: Rail flags
          type: array
          items:
            type: string
    TransportationDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the transportation segment.
          example: '12345'
        type:
          type: string
          description: Type of segment.
          example: Feature
        geometry:
          description: Geometric representation of the segment.
          allOf:
            - $ref: '#/components/schemas/GeometryDto'
        properties:
          description: Properties and additional details.
          allOf:
            - $ref: '#/components/schemas/TransportationPropertiesDto'
      required:
        - id
        - type
        - geometry
        - properties
    DivisionBboxDto:
      type: object
      properties:
        xmin:
          type: number
          description: Minimum longitude
          example: -74.3
        xmax:
          type: number
          description: Maximum longitude
          example: -73.7
        ymin:
          type: number
          description: Minimum latitude
          example: 40.5
        ymax:
          type: number
          description: Maximum latitude
          example: 40.9
      required:
        - xmin
        - xmax
        - ymin
        - ymax
    DivisionPropertiesDto:
      type: object
      properties:
        subtype:
          type: string
          description: Subtype of the division
        class:
          type: string
          description: Class of the division
        primary_name:
          type: string
          description: Primary name of the division
          example: City of Westminster
        names:
          type: object
          description: Names of the division, including common names keyed by language code
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: GB
        region:
          type: string
          description: ISO 3166-2 region code
          example: GB-WSM
        admin_level:
          type: number
          description: >-
            Position of the division in its country's hierarchy, e.g. 0
            (country), 1, 2.
          example: 2
        is_land:
          type: boolean
          description: Whether the area represents land (vs maritime).
          example: true
        is_territorial:
          type: boolean
          description: Whether the area includes territorial waters.
          example: false
        division_id:
          type: string
          description: ID of the division feature this area belongs to.
        ext_geometry_source:
          type: string
          description: >-
            Set when this record's own geometry is missing upstream and the
            boundary was served from a sibling area of the same division; the
            value is the sibling's class, e.g. "maritime" (land plus territorial
            waters).
          example: maritime
    DivisionDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the division area.
          example: '12345'
        type:
          type: string
          description: Type of division.
          example: division_area
        bbox:
          description: Bounding box of the division area.
          allOf:
            - $ref: '#/components/schemas/DivisionBboxDto'
        geometry:
          description: >-
            Geometric representation of the division area. Omitted when
            include_geometry resolves to false; fetch it via GET
            /divisions/{id}.
          allOf:
            - $ref: '#/components/schemas/GeometryDto'
        properties:
          description: Properties and additional details.
          allOf:
            - $ref: '#/components/schemas/DivisionPropertiesDto'
      required:
        - id
        - type
        - properties