Dropoffs [NEW]

Adds structured dropoff support, allowing predefined or customer-defined end-of-tour return locations, including time-window details.

This capability has already been approved by the Specification Committee and is currently pending final ratification by the OCTO Board of Directors. Once ratified, it will become an official part of the OCTO standard. The implementation details described in this document reflect the approved specification and are not expected to change, but final adoption is subject to the Board’s formal vote.

Business Context

Dropoff service is commonly offered for tours and activities. It allows customers to be returned to one of the designated locations, or even to a customer-defined point within a supported dropoff area, instead of being left at the main ending point.

This service may be included for free or offered at an additional cost.

The OCTO Dropoffs Capability allows:

• Supplier systems to indicate whether a product option supports dropoff, whether dropoff is required, and to provide structured dropoff locations and areas.

• Reseller systems to obtain dropoff data, display available choices to customers during the booking flow, pass the customer’s selected dropoff location when creating, confirming, or updating a booking, and leverage a capability-specific endpoint to validate dropoff availability based on a customer-defined point (e.g., latitude/longitude).

Identical functionality is also available for pickups through the Pickups, which mirrors dropoffs and provides structured or customer-defined start-of-tour collection options.

Capability Summary

To enable this capability when supported by a supplier system’s OCTO API, the reseller system must include dropoffs in the Octo-Capabilities header of its requests to the supplier system.

Adding dropoffs to your Octo-Capabilities header will alter OCTO Core endpoint behavior as follows:

Endpoint	Dropoffs Capability Enhancements to OCTO Core
Get Supplier	No additional functionality.
Get Product List	Response payload includes, per product option, whether dropoff is available, required for booking, and a list of supported locations/areas with their details.
Get Product	Response payload includes, per product option, whether dropoff is available, required for booking, and a list of supported locations/areas with their details.
Availability Calendar	Request can specify if the customer wants dropoff and the chosen location. Response includes, per calendar day, whether dropoff is available, required, and the list of supported locations/areas with details.
Availability Check	Request can specify if the customer wants dropoff and the chosen location. Response includes, per availability, whether dropoff is available, required, the list of supported locations/areas with details, including dropoff time window.
Create Booking	Request can specify if the customer wants dropoff, the chosen location, as well as any dropoff notes for booking. Response includes if the dropoff is requested for the booking, the selected dropoff location with details, including the dropoff time window.
Extend Pending Booking Expiration	Response includes if the dropoff is requested for the booking, the selected dropoff location with details, including the dropoff time window.
Confirm Booking	Response includes if the dropoff is requested for the booking, the selected dropoff location with details, including the dropoff time window.
Cancel Booking	Response includes if the dropoff is requested for the booking, the selected dropoff location with details, including the dropoff time window.
Update Booking	Request can specify if the customer wants dropoff, the chosen location, as well as any dropoff notes for booking. Response includes if the dropoff is requested for the booking, the selected dropoff location with details, including the dropoff time window.
Get Booking List	Response includes if the dropoff is requested for the booking, the selected dropoff location with details, including the dropoff time window.
Get Booking	Response includes if the dropoff is requested for the booking, the selected dropoff location with details, including the dropoff time window.

GET Booking Dropoff Locations Endpoint

Additionally, this capability provides a dedicated endpoint GET Booking Dropoffs Locations, which enables searching for dropoff locations based on a customer-defined latitude and longitude, and validates whether dropoff service is available at that exact location or recommends alternate dropoff locations.

Additional OCTO Core Parameters & Schemas

GET Product List AND GET Product (with dropoffs)

Request Body:

{
// ...rest of the OPTION object
  "dropoffAvailable": true,
  "dropoffRequired": false,
  "dropoffLocations": [
    {
      "id": "c1b2a3d4-5e6f-7081-92a3-b4c5d6e7f801",
      "title": "Sagrada Família",
      "shortDescription": "Dropoff available near the Basílica de la Sagrada Família in Barcelona. Guests are dropped at the coach parking area on Carrer de la Marina.",
      "place": {
        "latitude": 41.4036,
        "longitude": 2.1744,
        "postalAddress": {
          "streetAddress": "Carrer de la Marina, 253",
          "addressLocality": "Barcelona",
          "addressRegion": "Catalunya",
          "postalCode": "08013",
          "addressCountry": "ES",
          "postOfficeBoxNumber": null
        },
        "identifiers": [
          { "googlePlaceId": "ChIJp2VwQ0-hpBIRsY0R5pY2W7E" },
          { "tripadvisorLocationId": "876543" }
        ],
        "sameAs": [
          "https://maps.google.com/?cid=11111111111111111111"
        ]
      }
    },
    {
      "id": "f9e8d7c6-b5a4-3210-98f7-e6d5c4b3a210",
      "title": "Plaça de Catalunya",
      "shortDescription": "Central Barcelona dropoff at Plaça de Catalunya. Guests meet at the bus bays on the south side of the square.",
      "place": {
        "latitude": 41.3870,
        "longitude": 2.1701,
        "postalAddress": {
          "streetAddress": "Plaça de Catalunya",
          "addressLocality": "Barcelona",
          "addressRegion": "Catalunya",
          "postalCode": "08002",
          "addressCountry": "ES",
          "postOfficeBoxNumber": null
        },
        "identifiers": [
          { "googlePlaceId": "ChIJD7fiBh9uQgwR7-8fITgxTmU" }
        ],
        "sameAs": [
          "https://maps.google.com/?cid=22222222222222222222"
        ]
      }
    }
  ],
  // Optional, just intended as a visual aid
  "dropoffAreas": [
    {
      "title": "Central Barcelona Zone",
      "shortDescription": "Dropoff available across central Barcelona, including Eixample, the Gothic Quarter, and the waterfront around Port Vell. Guests are dropped at approved coach stops within this zone.",
      "area": {
        "coordinates": [
          { "latitude": 41.3945, "longitude": 2.1682 },
          { "latitude": 41.3891, "longitude": 2.1830 },
          { "latitude": 41.3758, "longitude": 2.1820 },
          { "latitude": 41.3769, "longitude": 2.1635 },
          { "latitude": 41.3945, "longitude": 2.1682 } // end up where you start
        ],
        "identifiers": [
          { "googlePlaceId": "ChIJ5TCOcRaipBIRX9G6FFzC7m8" },
          { "tripadvisorLocationId": "654321" }
        ],
        "sameAs": [
          "https://maps.google.com/?cid=33333333333333333333",
          "https://www.tripadvisor.com/Attraction_Review-central-barcelona"
        ]
      }
    }
  ]
}

POST Availability Calendar (with dropoffs)

Request Body:

{
  // ... rest of the OCTO Core availability request body
  "dropoffRequested": true,
  "dropoffLocationId": "9f1a3c1e-6b28-4e2a-9c7e-32d5a3a1f45e"
}

Field	Type	Required	Description
dropoffRequested	boolean	optional	Whether the customer requested dropoff.
dropoffLocationId	string	optional	The dropoff location ID selected by the customer (must match one of dropoffLocations[].id).

Response Body:

{
  // ...rest of the CALENDAR DAY object
  "dropoffAvailable": true,
  "dropoffRequired": false
}

Field	Type	Required	Description
dropoffAvailable	boolean	required	Indicates whether dropoff service is offered for this date.
dropoffRequired	boolean	required	Indicates whether selecting a dropoff location is mandatory for booking.

POST Availability Check (with dropoffs)

Request Body:

{
// ... rest of the OCTO Core availability request body
  "dropoffRequested": true,
  "dropoffLocationId": null (optional, if dropoffLocation is requested up-front)
}

Field	Type	Required	Description
dropoffRequested	boolean	optional	Whether the customer requested dropoff.
dropoffLocationId	string	optional	The dropoff location ID selected by the customer (must match one of dropoffLocations[].id).

Response Body:

{
// ...rest of the AVAILABILITY object
  // ...note addition of localDateTimeStart and localDateTimeEnd below 
  "dropoffAvailable": true,
  "dropoffRequired": false,
  "localDropoffDateTimeStart": null, (only set if dropoffLocationId is set)
  "localDropoffDateTimeEnd": null, (only set if dropoffLocationId is set)
}

Field	Type	Required	Description
localDropoffDateTimeStart	string (ISO 8601, i.e. YYYY-MM-DD)	optional	Start of the dropoff time window in the local time zone of the dropoff location. Indicates the earliest time the customer can be collected.
localDropoffDateTimeEnd	string (ISO 8601, i.e. YYYY-MM-DD)	optional	End of the dropoff time window in the local time zone of the dropoff location. Indicates the latest time the customer can be collected.

POST Create Booking / PATCH Update Booking (with dropoffs)

Request Body:

{
// ... rest of the OCTO Core CREATE BOOKING request body
  "dropoffRequested": true,
  "dropoffLocationId": "9f1a3c1e-6b28-4e2a-9c7e-32d5a3a1f45e"
  "dropoffNotes": "Blue door next to the bakery"
}

Field	Type	Required	Description
dropoffRequested	boolean	optional	Whether the customer requested dropoff.
dropoffLocationId	string	optional	The dropoff location ID selected by the customer (must match one of dropoffLocations[].id).
dropoffpNotes	string	optional	Free-text notes provided by the customer for dropoff (e.g., Airbnb directions, gate code, nearby landmark, hotel room, etc).

Response Body:

// ...rest of the BOOKING object
{
  "dropoffRequested": true,
  "dropoffLocationId": "a3f9c2d1-7e45-4b89-91f2-5d6e7c8b9a10",
  "dropoffNotes": "Main entrance under the glass canopy",
  "localDropoffDateTimeStart": "2025-06-15T18:10:00+02:00",
  "localDropoffDateTimeEnd": "2025-06-15T18:25:00+02:00",
  "dropoffLocation": {
    "id": "a3f9c2d1-7e45-4b89-91f2-5d6e7c8b9a10",
    "title": "Hotel Colosseo View",
    "shortDescription": "Dropoff available at Hotel Colosseo View, a short walk from the Colosseum. Guests should wait at the coach bay in front of the main entrance on Via dei Fori Imperiali.",
    "place": {
      "latitude": 41.8910,
      "longitude": 12.4923,
      "postalAddress": {
        "streetAddress": "Via dei Fori Imperiali 12",
        "addressLocality": "Roma",
        "addressRegion": "Lazio",
        "postalCode": "00184",
        "addressCountry": "IT",
        "postOfficeBoxNumber": null
      },
      "identifiers": [
        { "googlePlaceId": "ChIJ0X31pIKJPxMRXkS7Gz5Q2f8" },
        { "tripadvisorLocationId": "789012" }
      ],
      "sameAs": [
        "https://maps.google.com/?cid=44444444444444444444"
      ]
    }
  }
}

GET Booking Dropoff Locations

GET {host}/bookings/{uuid}/dropoffLocations?latitude={lat}&longitude={lng}

Query Parameters:

Name	Type	Required	Description
latitude	number	required	Customer-defined latitude (WGS84).
longitude	number	required	Customer-defined longitude (WGS84).

When latitude and longitude are not provided, the supplier system should return the full list of dropoff locations.

When latitude and longitude are provided, the supplier system may choose to either:

• return the full list of dropoff locations in any order,

• return the full list ordered in a way that reflects the lat/lon query,

• return only a subset of locations that best match the passenger’s position, or

• generate a new, virtual dropoff location on the fly that corresponds to the provided coordinates and can be used for booking creation or updates.

Reseller systems must be prepared for scenarios where a dropoff location ID returned during availability or booking does not appear in the static list retrieved via the general dropoffLocations query for that product option.

Response Body:

{
  "localDropoffDateTimeStart": "2025-09-14T14:20:00+01:00",
  "localDropoffDateTimeEnd": "2025-09-14T14:35:00+01:00",
  "dropoffLocation": {
    "id": "b72c4e81-9d3f-4a3c-8a6f-0e92c4b1d993",
    "title": "Paddington Station – Praed St Entrance",
    "shortDescription": "Dropoff at the main Praed Street entrance, next to the taxi rank.",
    "place": {
      "latitude": 51.5167,
      "longitude": -0.1761,
      "postalAddress": {
        "streetAddress": "Praed Street",
        "addressLocality": "London",
        "addressRegion": "England",
        "postalCode": "W2 1HB",
        "addressCountry": "UK"
      },
      "identifiers": [
        { "googlePlaceId": "ChIJ5wCQT3YPdkgR0b6l5LjxaQ8" }
      ],
      "sameAs": [
        "https://maps.google.com/?q=Paddington+Station+Praed+Street"
      ]
    }
  }
},
{
  "localDropoffDateTimeStart": "2025-09-14T14:50:00+01:00",
  "localDropoffDateTimeEnd": "2025-09-14T15:05:00+01:00",
  "dropoffLocation": {
    "id": "e19a873b-04c3-48cc-9cb0-78bbcf6c1f44",
    "title": "London Eye – Riverside Walk",
    "shortDescription": "Dropoff near the entrance queue area on Riverside Walk.",
    "place": {
      "latitude": 51.5033,
      "longitude": -0.1195,
      "postalAddress": {
        "streetAddress": "Riverside Walk",
        "addressLocality": "London",
        "addressRegion": "England",
        "postalCode": "SE1 7PB",
        "addressCountry": "UK"
      }
    }
  }
}