Cabify Estimates API

openapi: 3.0.0
info:
  description: 'Welcome to the Cabify Logistics API. This API allows you to create and manage parcel deliveries, track their status in real time, configure proof of delivery options, and receive live updates via webhooks. All requests must be authenticated using a Bearer token.

    '
  version: 1.0.0
  title: Cabify Logistics delivery Estimates API
  contact:
    email: p.delivery@cabify.com
servers:
- url: https://logistics.api.cabify.com
  description: Production
- url: https://logistics.api.cabify-sandbox.com
  description: Sandbox
tags:
- description: This method returns prices, Id's and all the information for products that are available at the origin point. Before requesting a journey as a first step it is necessary to obtain the different products configured in your account in order to select the one that fits your needs and keep the Id that will be used in the Journey.
  name: Estimates
paths:
  /api/v4/estimates:
    post:
      callbacks: {}
      description: 'Obtain prices, product IDs, and all the information for products that are available at the origin point.


        > ❗️ Important

        >

        > You **must** call this endpoint before creating a Journey. The response provides the `product.id`

        > that should be passed to the journey creation endpoint.

        >

        > For **reserved** journeys, pass the same `start_at` used here to the journey creation request

        > to guarantee consistent product availability and pricing.

        >

        > We recommend estimating no more than **5 minutes** before creating the journey.


        ## Response


        The response contains an array of available products, each with:

        - `product.id` — pass as `product_id` when creating a journey

        - Estimated price and currency

        - ETA (estimated time of arrival)

        - Vehicle category information


        ## Hub Information


        When the origin is within a large venue (airport, train station, etc.), each estimation object may include a `hub` field containing:

        - Hub metadata (uid, title, location_id)

        - A list of **meeting points** — designated pick-up locations with coordinates, images, and localized instructions


        The `hub` field is resolved on a best-effort basis in parallel with pricing. It may be `null` if hub resolution does not complete in time or no hub exists at the origin.


        > 📘 Using Hub Data

        >

        > When a hub is present, present the meeting points to the user for selection and include the chosen one in the journey creation request via the `meeting_point` field in the origin stop.

        > Alternatively, use `GET /api/v4/hub` to look up hub data independently.

        '
      operationId: getEstimation
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EstimateRequest'
        description: Estimate request
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EstimateResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedRequest'
          description: Unauthorized
        '500':
          content:
            application/text:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal server error
      summary: Create estimation
      tags:
      - Estimates
components:
  schemas:
    HubObject:
      description: A hub is a large venue (e.g. airport, train station) with designated pick-up/drop-off meeting points.
      example:
        active: true
        location_id: location-4
        meeting_points:
        - bottom_image_url: https://example.com/t1-bottom.png
          coordinates:
            latitude: 40.4722
            longitude: -3.5608
          header_image_url: https://example.com/t1-header.png
          instructions:
          - en: Head to the main gate of Terminal 1
            es: Dirígete a la puerta principal de la Terminal 1
            step_image_url: https://example.com/step1.png
          title:
            en: Terminal 1
            es: Terminal 1
          uid: mp-loc4-1
        title:
          en: Madrid Barajas
          es: Madrid Barajas
        uid: hub-loc4
      nullable: true
      properties:
        active:
          description: Whether the hub is currently active.
          type: boolean
        location_id:
          description: Location identifier used to look up this hub.
          type: string
        meeting_points:
          description: Designated pick-up/drop-off points within the hub. Present one of these to the user as their boarding location.
          items:
            properties:
              bottom_image_url:
                description: URL for the bottom image of the meeting point.
                nullable: true
                type: string
              coordinates:
                description: GPS coordinates of the meeting point.
                properties:
                  latitude:
                    type: number
                  longitude:
                    type: number
                type: object
              header_image_url:
                description: URL for the header image of the meeting point.
                nullable: true
                type: string
              instructions:
                description: Step-by-step instructions to reach the meeting point.
                items:
                  properties:
                    en:
                      type: string
                    es:
                      type: string
                    step_image_url:
                      nullable: true
                      type: string
                  type: object
                type: array
              title:
                additionalProperties:
                  type: string
                description: Localized name of the meeting point, keyed by BCP 47 language tag.
                type: object
              uid:
                description: Unique identifier of the meeting point.
                type: string
            type: object
          type: array
        title:
          additionalProperties:
            type: string
          description: Localized name of the hub, keyed by BCP 47 language tag.
          type: object
        uid:
          description: Unique identifier of the hub.
          type: string
      title: HubObject
      type: object
    InternalServerError:
      description: indicates that an internal server error occurred
      example:
        error: Something went wrong
      properties:
        error:
          type: string
      title: InternalServerError
      type: object
    BadRequest:
      description: Indicates that the server cannot or will not process the request due to something that is perceived to be a client error (for example, malformed request syntax, invalid request message framing, or deceptive request routing).
      example:
        error: Bad Request error message
      properties:
        message:
          type: string
      title: BadRequest
      type: object
    UnauthorizedRequest:
      description: The token used is invalid either because it is expired or because it is incorrect.
      example:
        error: Unauthorized
      properties:
        error:
          type: string
      title: UnauthorizedRequest
      type: object
    EstimateRequest:
      additionalProperties: false
      description: 'Request an estimate before creating a journey.


        The estimation response provides the `product.id` value that **must** be passed to the journey

        creation endpoint. For **reserved** journeys, also pass the same `start_at` used here to the

        journey creation request to ensure consistent pricing and availability.


        We recommend requesting a new estimate no more than **5 minutes** before creating a journey.

        '
      example:
        requester_id: 0d3cd443da5f11eb89d7ea639ff4befb
        start_at: '2022-07-01 10:00:00'
        start_type: asap
        stops:
        - loc:
          - 40.4169335
          - -3.7061872
        - loc:
          - 40.4169335
          - -3.7061872
      properties:
        requester_id:
          description: User to which the estimates would be scoped.
          nullable: false
          pattern: ^[a-f0-9]{32}$
          type: string
        start_at:
          description: When using startType RESERVED this attribute defines the date and time of the reservation. Accepted format must be YYYY-MM-DD HH:MM:SS. It should be in the local time of the pick up location.
          nullable: true
          pattern: ^([0-9]+(-[0-9]+)+)\s+([0-9]+(:[0-9]+)+)$
          type: string
        start_type:
          description: Specifies whether the journey should start right now or it should be a reservation later in time. Note that if the value is RESERVED startAt attribute has to be a valid date. If ASAP startAt will be ignored.
          enum:
          - asap
          - reserved
          nullable: false
          type: string
        stops:
          default: []
          description: The actual coordinates of the address. Required two floats per location latitude and longitude.
          items:
            properties:
              loc:
                items:
                  type: number
                maxItems: 2
                minItems: 2
                type: array
            type: object
          minItems: 2
          type: array
      required:
      - start_type
      - requester_id
      - stops
      title: EstimateRequest
      type: object
    EstimateResponse:
      description: 'List of available products with pricing for the requested route.


        Each item contains the `product.id` needed to create a journey. Use this value as `product_id`

        in the journey creation request.

        '
      example:
      - distance: 1831
        duration: 1260
        eta:
          formatted: 10 min
          low_availability: true
        product:
          description: The standard option, with all the usual perkss
          id: d79565b5b64d9d46549925c254793937
          name: Cabify Executive.
          service_type: WIP
          slug: slug_code_1000
        route: ukbvFnjhU[c@k@m@_@[SOMKKGKIIGGKW]???GAEAC?AAAAAIIIEGCI?I?MLELCHCJAJARDREXG`@AFELa@jBMp@i@~BKd@GZo@vCQt@GPOf@??SEUAS?SDSDSHQLONCBCDCDCBCDCDCDCDM^ANCNAPAR?P?T@P@RHb@J\NZ]r@GLCHMRMTMVYj@Yd@y@|AWf@qA`CU`@Yf@OZSZO\mAzBU\ELGJGJEH]p@Wd@kAvBm@fAABOXWd@W`@m@jAeAlBwAjCW^mAzBWf@S^OTA@C@CBCBE@KF??UMYQSGo@w@w@y@WYwA}ACCWY[][]AAYYo@o@CC]_@CCOG??IKOOiAwAMOY]a@c@c@c@i@k@SQKK_A}@gA_As@k@USCAy@o@cAs@_@W]YIIc@a@AAc@[iAaA[Y_@]o@g@gA}@AAc@]_@W]UOKOIQKe@UIE_@QA?OGOGa@OA?OEOEYIICA?OEUEa@GYGWCKASCi@Gk@Cs@CG?WAg@AA?i@AA?e@?c@?c@Ac@?I?G?U?I?]@o@@W?K@W?c@@c@@c@@C?_@A[AG?EAOAM?AAG?OAIA_@EA?c@GOAw@MCAc@KMEOA[Kw@Uc@O}@]m@WKEc@Uy@e@o@a@QMgAw@OMAA]We@_@q@m@ECIIIIGECEw@s@[[yAsAi@i@AAEEYWCAUSOMMIGGWSGEECSOCAQMECKGQIAAYMSKKE]O[Kg@QWIc@Ky@SQCq@KMCG?_@GAA_@Em@I{G}@]Ga@IMEg@Mm@Qm@WWKOIe@WUK[Qa@Qk@]KGy@g@oAs@k@]i@]}AiA_@[GEmAcAo@m@EAGCKKWU[Ua@[g@Y}@e@ECuCkA[MGEGA[Ou@]sAu@??UAC?YQy@g@i@_@IGc@]cA_AMKm@m@aAeAEAQASYo@_AsAoBsA}B[m@[m@GMOYMYYo@u@iBu@oBg@}AEMq@}BKa@I]GWQq@GYWsAQiAM{@Gk@AIKu@AQE_@Em@Gk@Cm@C]AOEcACmACoA?wA?O?G?M@K?m@@o@Bo@HwAFcAB[?ANaBBY@OD[PwANaA?EJs@V{AJi@DQ?ABSx@qEPoANkALkALaBBY?A@[NaCDsAB}ABoB?oBAuBEuBGuBIgBM}BEUM_BQeBKw@MaAKw@Im@]oB_@mBUcASaAMe@c@eBe@_BGSUq@CGWy@Qi@Wq@m@yAc@gAQ_@Ue@Wi@m@kAYg@a@o@cAaBgBiC_@g@IKGKKKGI}@aAEGu@y@e@e@e@c@o@k@e@a@e@a@g@a@a@Yi@a@o@a@A?qAy@[Qe@We@Us@_@_@OUI[MEAk@UICQGOGKCcFqAoAWkAScAOmAMo@Gm@EYCu@CWAYAwAAa@?c@?c@?A?_B@qAB_CDE?a@@w@@W@wB@cA?cB@c@AaAAC?g@AgAGg@CYEA?WEKAUEUEA?YEUEQE[GOESEMEWGCAA?UIOEUIWIa@Ou@[[O]Ou@a@WO}@k@WSCAm@e@e@_@KIQQCAACWUs@s@k@m@MQKKq@{@QUCECCw@kAuAwBoCoE_@m@We@sCqE[i@uAyBS]AAGMMQIOaBiCmB}CsF{IGKOWa@o@iDqFOWKOe@w@mAqBGKc@q@EIi@{@Wc@QUGKa@q@g@s@AAW[UYEGOQIKKMOOIIYYUUm@m@KI]Y}@w@wCyB{@o@o@e@gC_BCC_@UQKy@e@w@c@o@]i@WsDgBoBy@oAg@g@QkAc@u@UEC[IA?]MwBk@oBg@MCi@MuDs@}@QOCw@I[E[EcAQmDc@??OQAAOEa@IoAQoAOa@G_@GQCSEQGEACCg@[UUGG[]g@g@UOQK]OEASE_@Ei@EMAA?MD??{EUeCOMCw@G??YMECEECAMS??AK?MAKAKCIEIEIIGAAAAA?AAAAA?A?AAA?AAA?A?A?A?IAE?G@GDIDEFGFEHCHAJALAH?J@J@JBHBHDFFFFBHDGd@?@?@@HADKf@GZETEJKNEFIDIBOBM?MCi@Ku@QYCUAW?W@_@Be@Bc@BA?[BG?MACAECGEA?IKOQ??FIBC@EBMCWCMEECCGCIAI@A@C@GDEFEN?P@F@DJNA^AL?@?D?FBHBHDHBBVPJDZJDBDFBB@P@B?BALAHCFADCBCDCBABGDCBA@_@VCDYLA@_@R_@PIDc@TSLOHQL[VIDSL[NIDKDSFoCr@g@N_AV[HgAVSFYFe@L]HcAL[D]Ho@LKBM?O?KA_@A_@BKD???AAA?AAA?AA??AC?A?A?C?A?A@A?A@A@?@A@CBA@ABA@?BA@?BA@?B?B?@?B?@?B@@C@ORCBWr@CH{@tB?@Sh@GPERCRGX?FC`@Ej@CNEPIVO\_AvB]t@GNK\c@z@Wh@MXEJWl@MXg@lA]v@s@~AUh@KV?@ADABAD?BAD?B?BAD?D@B?D?BBr@?BDv@D`ABX@N@H@J@FBF@FBJDNDJ@D@BNZLRT^^j@@@BD@D@BBD@F@D@F@N@H@H?J?D?F?JAF?DAFAHAFi@dCQv@UjASbAPzA?FDZLzA?@Dl@Dj@Bp@Dl@Bt@@LD`A?D?h@Al@Af@?FAv@Ad@??LOJOBAPc@@ARo@z@eCFSTu@BE@C@CBABE@ABCBABADCDABAVC\?H?fAFb@Bb@BF?D?F@H?BA
        supplements:
        - kind: toll
          name: toll name
          pay_to_driver: true
          price:
            amount: 2332
            currency: EUR
        total:
          amount: 2332
          currency: EUR
      items:
        description: Supplements of a Journey.
        properties:
          distance:
            description: Calculated distance to travel in meters.
            type: integer
          duration:
            description: Estimated duration of the journey in seconds.
            type: integer
          eta:
            description: Estimated Time of Arrival.
            properties:
              formatted:
                description: 'ETA formatted as a string with the format: ''{minutes} min'''
                type: string
              low_availability:
                description: Is there low availability?.
                type: boolean
            type: object
          hub:
            $ref: '#/components/schemas/HubObject'
          product:
            description: Estimated product details.
            properties:
              description:
                description: Description of the product in english.
                type: string
              id:
                description: Unique identifier of the product. Pass this value as `product_id` when creating a journey.
                type: string
              name:
                description: Name of the product in english
                type: string
              service_type:
                description: WIP.
                type: string
              slug:
                description: Slug of the Label.
                type: string
            type: object
          route:
            description: List of estimated routes. These are in Google's PolylinFormat. See <a href='https://developers.cabify.com/docs/polyline-algorithm'>this section</a> for more info
            type: string
          supplements:
            description: List of supplements included in the estimation.
            items:
              description: Supplements of a Journey.
              properties:
                kind:
                  description: Kind of the Supplement.
                  type: string
                name:
                  description: Name of the Supplement.
                  type: string
                pay_to_driver:
                  description: Whether it should be paid to the Driver.
                  type: boolean
                price:
                  description: Total of the estimate.
                  properties:
                    amount:
                      description: Amount in cents. *For CLP this field is in currency units.
                      type: integer
                    currency:
                      description: Currency Code in ISO_4217 format.
                      type: string
                  type: object
              type: object
            type: array
          total:
            description: Supplements of a Journey.
            properties:
              amount:
                description: Amount in cents. *For CLP this field is in currency units.
                type: integer
              currency:
                description: Currency Code in ISO_4217 format.
                type: string
            type: object
        type: object
      title: EstimateResponse
      type: array
  securitySchemes:
    bearer_token:
      type: http
      scheme: bearer