Coordinate-based transfer search

The Booking API supports GPS coordinates and IATA codes as location identifiers for transfer searches. This means you can search transfers directly from a guest's GPS position — hotel, port, station — without needing to pre-map those locations to internal IDs.

Identification methods

Each origin and destination accepts exactly one of the following identification methods:

Method	How to send it	When to use it
Location ID (L prefix)	LocationOriginID="L4714" attribute	You have the internal location ID from static data
Accommodation ID (H prefix)	LocationOriginID="H1559666" attribute	You have the internal accommodation ID
GIATA code (G prefix)	LocationOriginID="G12345" attribute	You have the GIATA code for the accommodation
IATA code (airports only)	LocationOrigin subnode with <IATA>	Origin or destination is an airport
GPS coordinates	LocationOrigin subnode with <Coordinates>	You have a lat/lon from the guest's location (hotel, port, station, etc.)

The first three use the LocationOriginID / LocationDestinationID attributes directly in TransferOptions. IATA and GPS use the LocationOrigin / LocationDestination subnodes.

You can combine methods freely in the same request — for example, GPS origin with IATA destination. Existing integrations using ID-based searches continue to work without changes.

The Type attribute

LocationOrigin and LocationDestination accept an optional Type attribute that filters resolution by location type:

Value	Location type
A	Airport
H	Hotel / Accommodation
S	Station (train, bus)
P	Port

• When using IATA: Type="A" is required. IATA codes only identify airports.
• When using GPS coordinates: Type is optional. If omitted, the system resolves to the nearest location regardless of type. If provided, it filters to the nearest location of that type — useful when multiple location types are near the same coordinates.
• <Name> and <Address> cannot be sent alongside IATA — they only apply to GPS points.

AVAIL — sending coordinates

Add LocationOrigin and/or LocationDestination subnodes inside the existing TransferOptions node. Both subnodes share the same structure:

<TransferOptions Type="ROUNDTRIP" LocationOriginTime="HH:MM" LocationDestinationTime="HH:MM">

    <!-- GPS origin: coordinates identify the pickup point -->
    <LocationOrigin Type="H">
        <Name>Hotel name</Name>       <!-- Optional in AVAIL; see Commit section below -->
        <Address>Street address</Address>  <!-- Optional in AVAIL; see Commit section below -->
        <Coordinates>
            <Latitude>XX.XXXX</Latitude>   <!-- Decimal degrees, WGS84 -->
            <Longitude>YY.YYYY</Longitude>
        </Coordinates>
        <IATA></IATA>   <!-- Leave empty when using coordinates -->
    </LocationOrigin>

    <!-- IATA destination: airport identified by IATA code -->
    <LocationDestination Type="A">
        <Name></Name>
        <Address></Address>
        <Coordinates>
            <Latitude></Latitude>   <!-- Leave empty when using IATA -->
            <Longitude></Longitude>
        </Coordinates>
        <IATA>XYZ</IATA>
    </LocationDestination>

</TransferOptions>

info

Coordinates must be in decimal degrees (DD) format under the WGS84 standard — the format produced by all standard GPS and mapping APIs.

COMMIT — providing address data for GPS points

When any location in the AVAIL was identified by GPS coordinates, the system requires Name and Address for that point before confirming the booking. These can come from either source:

• From AVAIL — if <Name> and <Address> were already sent in the Avail request
• From COMMIT — via the <TransferAddress> node, for any field not yet provided

<Name> + <Address> in AVAIL	<TransferAddress> in COMMIT
Both provided (non-empty)	Optional
Missing or empty	Required

The <TransferAddress> node goes directly inside <objRequest>, before <Concepts>:

<TransferAddress
    OriginName="Physical name of the GPS origin point"
    OriginAddress="Street address"
    OriginAddress2="Additional address info"
    OriginPostalCode="Postal code"
    DestinationName=""
    DestinationAddress=""
    DestinationAddress2=""
    DestinationPostalCode=""
    />

Only populate fields for GPS points. Fields for points identified by ID or IATA are ignored.

---

Validation rules

Identification rules

• You must provide exactly one identification method per origin and per destination.
• Sending more than one (e.g., both coordinates and IATA) returns an error.
• Sending none also returns an error.

Coordinate rules

• Both <Latitude> and <Longitude> are required. Sending only one returns an error.
• Format: decimal degrees (DD), WGS84.

IATA rules

• Type="A" is required when using an IATA code.
• If Type="A" is set, an IATA code must be provided — coordinates are not accepted for airports.
• <Name> and <Address> cannot be sent alongside an IATA code.

Same origin/destination

• Requests where origin and destination resolve to the same location are rejected — whether identified by ID, IATA, or coordinates.
• Exception: hotel-to-hotel transfers.

tip

For the full list of error messages and suggested actions, see the Error List page.

---

Examples

Hotel (GPS) → Airport (IATA) — full flow

The most common GPS scenario: pickup from a GPS position, dropoff at an airport. The Avail includes Name and Address in the origin, so TransferAddress is optional in Commit — but shown here for completeness.

Avail

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <DestServicesAvailV2 xmlns="http://xml.ineedtours.com/ws/">
            <objCredentials>
                <Source>
                    <RequestorID Type="DSP" ID="{{User}}" MessagePassword="{{Pass}}"/>
                </Source>
            </objCredentials>
            <objRequest PrimaryLangID="ES">
                <ServiceType>T</ServiceType>
                <StayDateRange Start="YYYY-MM-DD" End="YYYY-MM-DD"/>
                <Occupations>
                    <AvailRequestV2Occupation>
                        <Type>ADL</Type>
                        <Age>30</Age>
                    </AvailRequestV2Occupation>
                </Occupations>
                <TransferOptions Type="ROUNDTRIP" LocationOriginTime="10:00" LocationDestinationTime="15:00">
                    <LocationOrigin Type="H">
                        <Name>Hotel Test</Name>
                        <Address>Origin Test Address</Address>
                        <Coordinates>
                            <Latitude>52.3657</Latitude>
                            <Longitude>4.88807</Longitude>
                        </Coordinates>
                        <IATA></IATA>
                    </LocationOrigin>
                    <LocationDestination Type="A">
                        <Name></Name>
                        <Address></Address>
                        <Coordinates>
                            <Latitude></Latitude>
                            <Longitude></Longitude>
                        </Coordinates>
                        <IATA>AMS</IATA>
                    </LocationDestination>
                </TransferOptions>
            </objRequest>
        </DestServicesAvailV2>
    </soap:Body>
</soap:Envelope>

Commit

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <DestServicesCommitV2 xmlns="http://xml.ineedtours.com/ws/">
      <objCredentials>
        <Source>
          <RequestorID Type="DSP" ID="{{User}}" MessagePassword="{{Pass}}"/>
        </Source>
      </objCredentials>
      <objRequest EchoToken="{{EchoToken}}" PrimaryLangID="ES"
          TransactionIdentifier="{{TransactionIdentifier}}"
          ClientReference="{{ClientReference}}">
        <!-- Origin fields required: Avail did not provide Name/Address for the GPS origin.
             Leave Destination* empty: destination was identified by IATA. -->
        <TransferAddress
            OriginName="Hotel Test"
            OriginAddress="Origin Test Address"
            OriginAddress2=""
            OriginPostalCode=""
            DestinationName=""
            DestinationAddress=""
            DestinationAddress2=""
            DestinationPostalCode=""
            />
        <Concepts>
          <CommitRequestV2Concept>
            <ConceptBookingCode>{{ConceptBookingCode_1}}</ConceptBookingCode>
            <Guests>
              <Guest>
                <GivenName>FIRST NAME</GivenName>
                <Surname>LAST NAME</Surname>
                <BirthDate>YYYY-MM-DD</BirthDate>
                <PhoneNumber>XXXXXXXXX</PhoneNumber>
              </Guest>
            </Guests>
            <Transfer ContactPhone="XXXXXXXXX" TransportDataOrigin="FLIGHT_NUMBER"/>
          </CommitRequestV2Concept>
          <CommitRequestV2Concept>
            <ConceptBookingCode>{{ConceptBookingCode_2}}</ConceptBookingCode>
            <Guests>
              <Guest>
                <GivenName>FIRST NAME</GivenName>
                <Surname>LAST NAME</Surname>
                <BirthDate>YYYY-MM-DD</BirthDate>
                <PhoneNumber>XXXXXXXXX</PhoneNumber>
              </Guest>
            </Guests>
            <Transfer ContactPhone="XXXXXXXXX" TransportDataDestination="FLIGHT_NUMBER"/>
          </CommitRequestV2Concept>
        </Concepts>
      </objRequest>
    </DestServicesCommitV2>
  </soap:Body>
</soap:Envelope>

---

Airport (ID) → Hotel (GPS)

Origin identified by Location ID, destination by GPS coordinates.

<TransferOptions Type="ROUNDTRIP" LocationOriginID="L8" LocationOriginTime="10:00" LocationDestinationTime="15:00">
    <LocationDestination Type="H">
        <Name>Hotel Test</Name>
        <Address>Address Destination Test</Address>
        <Coordinates>
            <Latitude>52.3657</Latitude>
            <Longitude>4.88807</Longitude>
        </Coordinates>
        <IATA></IATA>
    </LocationDestination>
</TransferOptions>

info

Only LocationDestination appears as a subnode — origin uses the LocationOriginID attribute directly in TransferOptions. There is no LocationOrigin subnode when searching by ID.

---

Hotel (ID) → Airport (IATA)

Traditional flow with no GPS — included here to illustrate how ID and IATA combine.

<TransferOptions Type="ROUNDTRIP" LocationOriginID="H1559666" LocationOriginTime="10:00" LocationDestinationTime="15:00">
    <LocationDestination Type="A">
        <Name></Name>
        <Address></Address>
        <Coordinates>
            <Latitude></Latitude>
            <Longitude></Longitude>
        </Coordinates>
        <IATA>AMS</IATA>
    </LocationDestination>
</TransferOptions>