openapi: 3.1.0
info:
  title: Analytics
  version: 2.0.0
  description: The Analytics API lets you query for insights about transit times.
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    name: Sendcloud API Support
    url: https://www.sendcloud.dev
    email: contact@sendcloud.com
servers:
  - url: https://panel.sendcloud.sc/api/v2
    description: Sendcloud Production
tags:
  - name: Transit times
    description: Get insights about average transit times per carriers and shipping methods
paths:
  /insights/carriers/transit-times:
    get:
      summary: Retrieve carrier transit times
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierTransitTime'
              examples:
                TransitTimes:
                  summary: Retrieve Carriers transit times
                  value:
                    transit_times:
                      - user_id: '1234'
                        carrier_code: postnl
                        from_country: NL
                        to_country: DE
                        start_date: '2022-12-31'
                        end_date: '2023-11-17'
                        total_parcels: 2406
                        transit_time: 82
                      - user_id: '1234'
                        carrier_code: dhl
                        from_country: DE
                        to_country: AT
                        start_date: '2021-12-31'
                        end_date: '2022-12-31'
                        total_parcels: 75422
                        transit_time: 51
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ValidationError:
                  summary: Validation error
                  value:
                    detail:
                      - loc:
                          - query
                          - carrier-code
                        msg: field required
                        type: value_error.missing
      operationId: sc-public-v2-analytics-get-carrier_transit_times
      description: |-
        Retrieves the average transit time of a parcel per carrier.
        You can filter the results by origin and destination country, as well as by start and end dates.
      tags:
        - Transit times
      x-mint:
        href: /api/v2/analytics/retrieve-carrier-transit-times
        content: |-
          <Info>
            OAuth2 scopes required: `read:analytics`. See [Scopes for OAuth apps](/api/v3/scopes).
          </Info>
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds:
            - read:analytics
      parameters:
        - schema:
            type: array
            items:
              type: string
              example: postnl
          in: query
          name: carrier_code
          description: selection of carriers
          required: true
        - schema:
            type: string
            example: DE
          in: query
          name: from_country
          description: origin country
        - schema:
            type: string
            example: NL
          in: query
          name: to_country
          description: destination country
        - schema:
            type: string
            format: date
            example: '2020-12-31'
          in: query
          name: start_date
          description: first delivery start date
        - schema:
            type: string
            format: date
            example: '2022-12-31'
          in: query
          name: end_date
          description: first delivery end date
  /insights/shipping-methods/transit-times:
    get:
      summary: Retrieve shipping method transit times
      x-mint:
        href: /api/v2/analytics/retrieve-shipping-method-transit-times
        content: |-
          <Info>
            OAuth2 scopes required: `read:analytics`. See [Scopes for OAuth apps](/api/v3/scopes).
          </Info>
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingMethodTransitTime'
              examples:
                TransitTimes:
                  summary: Retrieve Shipping method transit times
                  value:
                    transit_times:
                      - user_id: '1234'
                        carrier_code: postnl
                        shipping_method_code: postnl:standard/kg=0-23
                        from_country: NL
                        to_country: DE
                        start_date: '2022-12-31'
                        end_date: '2023-12-31'
                        total_parcels: 240
                        transit_time: 92
                      - user_id: '1234'
                        carrier_code: dhl
                        shipping_method_code: dhl:complete/standard
                        from_country: DE
                        to_country: AT
                        start_date: '2022-12-31'
                        end_date: '2023-12-31'
                        total_parcels: 752
                        transit_time: 53
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ValidationError:
                  summary: Validation Error
                  value:
                    detail:
                      - loc:
                          - query
                          - carrier-code
                        msg: field required
                        type: value_error.missing
                      - loc:
                          - query
                          - shipping-method-code
                        msg: field required
                        type: value_error.missing
      operationId: sc-public-v2-analytics-get-shipping_method_transit_times
      description: |-
        Retrieves the average transit time of a parcel per shipping method and carrier.
        You can filter the results by origin and destination country, as well as start and end dates.
      tags:
        - Transit times
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds:
            - read:analytics
      parameters:
        - schema:
            type: array
            items:
              type: string
              example: postnl:standard/kg=0-23
          in: query
          name: shipping_method_code
          description: selection of shipping methods
          required: true
        - schema:
            type: string
            example: DE
          in: query
          name: from_country
          description: origin country
        - schema:
            type: string
            example: NL
          in: query
          name: to_country
          description: destination country
        - schema:
            type: string
            format: date
            example: '2021-12-31'
          in: query
          name: start_date
          description: first delivery start date
        - schema:
            type: string
            format: date
            example: '2022-12-31'
          in: query
          name: end_date
          description: first delivery end date
components:
  schemas:
    Errors:
      title: Errors Object
      type: object
      properties:
        detail:
          title: Detail
          type: array
          items:
            $ref: '#/components/schemas/ErrorItem'
    ErrorItem:
      title: Error Item Object
      type: object
      properties:
        loc:
          title: Location
          type: array
          items:
            type: string
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
    CarrierTransitTime:
      type: object
      title: User Carrier Transit Times Object
      properties:
        transit_times:
          type: array
          description: array of transit time objects
          items:
            type: object
            properties:
              user_id:
                type: string
                example: '12345'
              carrier_code:
                type: string
                example: postnl
              to_country:
                type: string
                example: DE
              from_country:
                type: string
                example: NL
              start_date:
                type: string
                format: date
              end_date:
                type: string
                format: date
              total_parcels:
                type: integer
                description: total number of parcels matching the filters
                minimum: 0
              transit_time:
                type: number
                description: average transit times for the matching parcels
                minimum: 0
            required:
              - user_id
              - carrier_code
              - total_parcels
              - transit_time
      required:
        - transit_times
    ShippingMethodTransitTime:
      type: object
      title: User Shipping Method Transit Times Object
      properties:
        transit_times:
          type: array
          description: array of transit time objects
          items:
            type: object
            properties:
              user_id:
                type: string
                example: '12345'
              carrier_code:
                type: string
                example: postnl
              shipping_method_code:
                type: string
                example: express-postnl-1-3kg
              from_country:
                type: string
                example: ES
              to_country:
                type: string
                example: AT
              start_date:
                type: string
                format: date
              end_date:
                type: string
                format: date
              total_parcels:
                type: integer
                description: total number of parcels matching the filters
                minimum: 0
              transit_time:
                type: number
                description: average transit times for the matching parcels
                minimum: 0
            required:
              - user_id
              - shipping_method_code
              - total_parcels
              - transit_time
      required:
        - transit_times
  securitySchemes:
    HTTPBasicAuth:
      type: http
      description: Basic Authentication using API key and secrets is currently the main authentication mechanism.
      scheme: basic
    OAuth2ClientCreds:
      type: oauth2
      description: OAuth2 is a standardized protocol for authorization that allows users to share their private resources stored on one site with another site without having to provide their credentials. OAuth2 Client Credentials Grant workflow. This workflow is typically used for server-to-server interactions that require authorization to access specific resources.
      flows:
        clientCredentials:
          tokenUrl: https://account.sendcloud.com/oauth2/token/
          scopes:
            read:analytics: View your shipping analytics
            read:audit-log: View your account's audit log
            read:brand: View your brands
            write:brand: Manage your brands
            write:carrier: Configure carriers and contracts
            read:checkout: View your dynamic checkout configurations and templates
            read:event-subscription: View your event subscriptions
            write:event-subscription: Create and manage your event subscriptions
            read:integration: View your integrations
            write:integration: Connect and manage integrations
            read:invoice: View your invoices
            read:notification: View your notifications
            write:notification: Manage your notifications
            read:operational-settings: View your warehouses, shipping lanes, and other operational settings
            write:operational-settings: Manage your warehouses, shipping lanes, and other operational settings
            read:order: View your orders
            write:order: Import and process your orders
            read:organization: View organization settings
            write:organization: Change organization settings
            read:parcel: View your shipments and their tracking status
            write:parcel: Create, announce, and cancel shipments
            read:pickup: View carrier pickups and the options available for scheduling them
            write:pickup: Schedule and manage carrier pickups
            read:price: View shipping prices
            write:product: Manage your product catalog
            read:return: View your returns
            write:return: Create and manage returns
            read:return-settings: View your return settings
            write:return-settings: Configure your return settings
            read:service-point: View carrier service points
            read:shipping-method: View shipping methods, products and prices
            read:shipping-rule: View your shipping rules
            write:shipping-rule: Create and manage shipping rules
            read:support-ticket: View your support tickets
            write:support-ticket: Manage your support tickets
            read:tracking-message: View your tracking notifications
            write:tracking-message: Manage your tracking notifications
            read:tracking-page: View your tracking page
            write:tracking-page: Customize your tracking page
            read:user: Read your basic account information