openapi: 3.1.0
info:
  title: DHL Location Finder Unified API
  description: >-
    The DHL Location Finder Unified API provides search of DHL Service Points
    across DHL divisions by address, geographic coordinates, location ID, and
    keyword ID.
  version: "1"
x-generated-from: https://developer.dhl.com/api-reference/location-finder-unified
x-generated-by: claude-crawl-2026-05-08
servers:
  - url: https://api.dhl.com/location-finder/v1
    description: DHL Location Finder Unified API
security:
  - apiKey: []
paths:
  /find-by-address:
    get:
      summary: Find Service Points by address
      operationId: findByAddress
      parameters:
        - name: countryCode
          in: query
          required: true
          schema:
            type: string
        - name: postalCode
          in: query
          schema:
            type: string
        - name: addressLocality
          in: query
          schema:
            type: string
        - name: streetAddress
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/ProviderType'
        - $ref: '#/components/parameters/ServiceType'
        - $ref: '#/components/parameters/LocationType'
        - $ref: '#/components/parameters/Radius'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/HideClosedShops'
      responses:
        '200':
          description: Service Point list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePointList'
  /find-by-geo:
    get:
      summary: Find Service Points by geographic coordinates
      operationId: findByGeo
      parameters:
        - name: latitude
          in: query
          required: true
          schema:
            type: number
            format: double
        - name: longitude
          in: query
          required: true
          schema:
            type: number
            format: double
        - $ref: '#/components/parameters/ProviderType'
        - $ref: '#/components/parameters/ServiceType'
        - $ref: '#/components/parameters/LocationType'
        - $ref: '#/components/parameters/Radius'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/HideClosedShops'
        - name: countryCode
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Service Point list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePointList'
  /find-by-location-id/{id}:
    get:
      summary: Find Service Point by location ID
      operationId: findByLocationId
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Service Point detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePoint'
  /find-by-keyword-id/{keywordId}:
    get:
      summary: Find Service Points by keyword ID
      operationId: findByKeywordId
      parameters:
        - name: keywordId
          in: path
          required: true
          schema:
            type: string
        - name: countryCode
          in: query
          required: true
          schema:
            type: string
        - name: postalCode
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Service Point list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePointList'
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: DHL-API-Key
  parameters:
    ProviderType:
      name: providerType
      in: query
      schema:
        type: string
        enum: [parcel, express]
    ServiceType:
      name: serviceType
      in: query
      schema:
        type: string
    LocationType:
      name: locationType
      in: query
      schema:
        type: string
        enum: [servicepoint, postoffice, locker, pobox, postbox]
    Radius:
      name: radius
      in: query
      schema:
        type: integer
        default: 5000
    Limit:
      name: limit
      in: query
      schema:
        type: integer
    HideClosedShops:
      name: hideClosedShops
      in: query
      schema:
        type: boolean
  schemas:
    ServicePoint:
      type: object
      additionalProperties: true
      properties:
        url:
          type: string
        location:
          type: object
          additionalProperties: true
        name:
          type: string
        place:
          type: object
          additionalProperties: true
    ServicePointList:
      type: object
      additionalProperties: true
      properties:
        url:
          type: string
        locations:
          type: array
          items:
            $ref: '#/components/schemas/ServicePoint'