openapi: 3.2.0
info:
  title: Shipcloud Pickup Dropoff Locations API
  version: '1.0'
  contact:
    name: Developer Support
    email: developers@shipcloud.io
  termsOfService: https://www.shipcloud.io/en/terms-and-conditions
  description: 'Operations tagged Pickup Dropoff Locations across 2 of this provider''s published API definitions: shipcloud_v1_oai3.json, shipcloud-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.shipcloud.io/v1
security:
- basic_auth: []
tags:
- name: Pickup Dropoff Locations
paths:
  /pickup_dropoff_locations:
    parameters: []
    get:
      description: Search pickup dropoff locations by address or geographical coordinates.
      responses:
        '200':
          description: A successful response with a list of pickup dropoff locations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  pickup_dropoff_locations:
                    type: array
                    items:
                      $ref: '#/components/schemas/pickup_dropoff_location'
              examples:
                Pickup dropoff locations example:
                  value:
                    pickup_dropoff_locations:
                    - carrier_code: budbee
                      service_point_id: Service point ID
                      name1: Location name
                      city: Putten
                      zip_code: 3881 SH
                      street1: Voorthuizerstraat
                      house_number: '2'
                      country_code: NL
                      longitude: '5.610012906547574'
                      latitude: '52.26022679665733'
                      distance: 2564
                      distance_unit_of_measure: M
                      telephone_number: ''
                      pudo_hours:
                      - type: Open
                        day: 1
                        time_from: 08:00
                        time_until: '21:00'
                      - type: Open
                        day: 2
                        time_from: 08:00
                        time_until: '21:00'
                      - type: Open
                        day: 3
                        time_from: 08:00
                        time_until: '21:00'
                      - type: Open
                        day: 4
                        time_from: 08:00
                        time_until: '21:00'
                      - type: Open
                        day: 5
                        time_from: 08:00
                        time_until: '21:00'
                      - type: Open
                        day: 6
                        time_from: 08:00
                        time_until: '21:00'
                      pudo_additional_properties:
                      - type: LocationType
                        sub_type: Locker
                        value: ''
                      - type: Service
                        sub_type: Pick-up
                        value: ''
                      - type: PudoPoint
                        sub_type: Other
                        value: Estimated delivery 2023-05-13 12:30 (UTC)
                      pudo_measurements:
                      - type: Length
                        unit_of_measure: CM
                        value: 38.5
                      - type: Width
                        unit_of_measure: CM
                        value: 60
                      - type: Height
                        unit_of_measure: CM
                        value: 29.5
                      - type: Weight
                        unit_of_measure: G
                        value: 2000
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      parameters:
      - schema:
          type: string
          example: dhl, hermes
        in: query
        required: true
        name: carriers
        description: Must be set with the carrier names (see /carriers endpoint). Multiple carriers can be given as a comma separated list.
      - schema:
          type: string
          maxLength: 255
        in: query
        name: street
        description: The street with house number and addition if applicable of the address.
      - schema:
          type: string
          maxLength: 255
        in: query
        name: zip_code
        description: The zipcode of the address.
      - schema:
          type: string
          maxLength: 255
        in: query
        name: city
        description: The city of the address.
      - schema:
          type: string
          maxLength: 255
        in: query
        name: state
        description: The state, county or province of the address.
      - schema:
          type: string
          example: DE
          maxLength: 255
        in: query
        name: country
        description: The country of the address.
      - schema:
          type: number
          example: 53.5446081
        in: query
        name: latitude
        description: The geographical coordinate that specifies the north-south position.
      - schema:
          type: number
          example: 9.996158
        in: query
        name: longitude
        description: The geographical coordinate that specifies the east-west position.
      - schema:
          type: integer
          default: 10000
          minLength: 1
          maxLength: 2147483647
        in: query
        name: radius
        description: The search radius in meters.
      - schema:
          type: integer
          default: 10
          minLength: 1
          maxLength: 100
        in: query
        name: limit
        description: The maximum number of locations to include in the search result.
      summary: Get pickup dropoff locations
      tags:
      - Pickup Dropoff Locations
      x-summary-source: derived
      operationId: getPickupDropoffLocations
      x-operation-id-source: derived
    servers:
    - url: https://api.shipcloud.io/v1
components:
  headers:
    shicloud-Request-ID:
      description: An internal identifier that we generate for every request. If you encounter a problem with your request, please send us this id when opening a support case.
      schema:
        type: string
    RateLimit-Interval:
      description: The number of seconds the interval for this user is long (e.g. 60)
      schema:
        type: integer
    RateLimit-Reset:
      description: The number of seconds that shows when the request rate limit resets (e.g. 42)
      schema:
        type: integer
    RateLimit-Remaining:
      description: Remaining number of request in the current interval (e.g. 111)
      schema:
        type: integer
    RateLimit-Limit:
      description: A number that shows the overall limit of requests this user can send (e.g. 120)
      schema:
        type: integer
  responses:
    '402':
      description: You've reached a maximum that is defined in your current plan. Please upgrade to a higher plan.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Interval:
          $ref: '#/components/headers/RateLimit-Interval'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/shicloud-Request-ID'
    '403':
      description: You are not allowed to talk to this endpoint. This can either be due to a wrong authentication or when you're trying to reach an endpoint that your account isn't allowed to access.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Interval:
          $ref: '#/components/headers/RateLimit-Interval'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/shicloud-Request-ID'
    '500':
      description: Something has seriously gone wrong. Don't worry, we'll have a look at it. If the error persists, please don't hesitate to contact us by sending us an email containing the `X-Request-ID` header we've returned.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Interval:
          $ref: '#/components/headers/RateLimit-Interval'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/shicloud-Request-ID'
    '401':
      description: Something has gone wrong when authorizing with our API. Please check e.g. if you're trying to use your sandbox api key with an operation that can only be used with a live API key.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Interval:
          $ref: '#/components/headers/RateLimit-Interval'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/shicloud-Request-ID'
    '400':
      description: Your request was not correct. Please see the response body for more detailed information.
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  description: Strings that describe, what has gone wrong. We're tunnelling error responses from the carriers. When this is the case, we try to prefix an error with 'The carrier {xyz} returned the following error:'
                  type: string
          examples:
            Single error:
              value:
                errors:
                - simple error message
            Multiple errors:
              value:
                errors:
                - simple error message
                - another error message
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Interval:
          $ref: '#/components/headers/RateLimit-Interval'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/shicloud-Request-ID'
  schemas:
    pickup_dropoff_location:
      type: object
      x-examples:
        pickup_dropoff_location_example:
          carrier_code: budbee
          service_point_id: Service point ID
          name1: Location name
          city: Putten
          zip_code: 3881 SH
          street1: Voorthuizerstraat
          house_number: '2'
          country_code: NL
          longitude: '5.610012906547574'
          latitude: '52.26022679665733'
          distance: 2564
          distance_unit_of_measure: M
          telephone_number: ''
          pudo_hours:
          - type: Open
            day: 1
            time_from: 08:00
            time_until: '21:00'
          - type: Open
            day: 2
            time_from: 08:00
            time_until: '21:00'
          - type: Open
            day: 3
            time_from: 08:00
            time_until: '21:00'
          - type: Open
            day: 4
            time_from: 08:00
            time_until: '21:00'
          - type: Open
            day: 5
            time_from: 08:00
            time_until: '21:00'
          - type: Open
            day: 6
            time_from: 08:00
            time_until: '21:00'
          pudo_additional_properties:
          - type: LocationType
            sub_type: Locker
            value: ''
          - type: Service
            sub_type: Pick-up
            value: ''
          - type: PudoPoint
            sub_type: Other
            value: Estimated delivery 2023-05-13 12:30 (UTC)
          pudo_measurements:
          - type: Length
            unit_of_measure: CM
            value: 38.5
          - type: Width
            unit_of_measure: CM
            value: 60
          - type: Height
            unit_of_measure: CM
            value: 29.5
          - type: Weight
            unit_of_measure: G
            value: 2000
      properties:
        carrier_code:
          type: string
        service_point_id:
          type: string
        name1:
          type: string
        city:
          type: string
        zip_code:
          type: string
        street1:
          type: string
        house_number:
          type: string
        country_code:
          type: string
        longitude:
          type: string
        latitude:
          type: string
        distance:
          type: integer
          description: Distance in the unit of measure defined in distance_unit_of_measure
        distance_unit_of_measure:
          type: string
        telephone_number:
          type: string
        pudo_hours:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              day:
                type: integer
                minimum: 1
                maximum: 7
                description: Days are numbered from 1 to 7 (Monday to Sunday).
              time_from:
                type: string
              time_until:
                type: string
        pudo_additional_properties:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              sub_type:
                type: string
              value:
                type: string
        pudo_measurements:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              unit_of_measure:
                type: string
              value:
                type: number
      description: A single location of a carrier. Includes opening hours, additional properties and (optional) maximum package measurements.
      title: pickup_dropoff_location
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic
externalDocs:
  description: Find more info at the shipcloud developer portal
  url: https://developers.shipcloud.io
x-refined-from:
- shipcloud_v1_oai3.json
- shipcloud-openapi.yml