Coordinate-based transfer search in Booking API

Transfer search functionality using GPS coordinates and/or IATA codes is now available in the I Need Tours Booking API.

This improvement allows transfers to be searched in a much more flexible way, significantly reducing the need for prior mapping of locations and hotels and minimizing operational errors in your integration.

Currently available features

From now on, you can identify the origin and destination of a transfer using any of the following methods:

• Location ID — via LocationOriginID / LocationDestinationID with prefix L (as before)
• Accommodation ID — via LocationOriginID / LocationDestinationID with prefix H
• GIATA code — via LocationOriginID / LocationDestinationID with prefix G
• IATA code (for airports) — via LocationOrigin / LocationDestination subnodes
• GPS coordinates (latitude / longitude) — via LocationOrigin / LocationDestination subnodes

The first three methods use the LocationOriginID / LocationDestinationID attributes directly. IATA and GPS coordinates use the LocationOrigin / LocationDestination subnodes described below.

This functionality is fully backward compatible. Existing integrations will continue to work without changes, and you may decide which identifier to use in each request.

Integration changes (coordinate-based search)

To take advantage of this improvement, only two points in your current integration need to be adapted:

1. AVAIL method changes

To send coordinates, you only need to add new subnodes within the existing TransferOptions node:

TransferOptions with coordinate-based location nodes

<LocationOrigin Type="X">
  <Name></Name>
  <Address></Address>
  <Coordinates>
    <Latitude>xxx</Latitude>
    <Longitude>xxx</Longitude>
  </Coordinates>
  <IATA>xxxxx</IATA>
</LocationOrigin>

<LocationDestination Type="H">
  <Name></Name>
  <Address></Address>
  <Coordinates>
    <Latitude>xxx</Latitude>
    <Longitude>xxx</Longitude>
  </Coordinates>
  <IATA>xxxxx</IATA>
</LocationDestination>

info

Technical note: The <Coordinates> subnode must include <Latitude> and <Longitude> in decimal degrees (DD) under the WGS84 standard, which is globally used by GPS systems.

The system is fully flexible: you may combine ID + IATA + coordinates in the same request depending on your needs.

Examples:

• Origin by ID (e.g. a station) and destination by coordinates (hotel)
• Origin by IATA (airport) and destination by coordinates (port, station, or hotel)

2. COMMIT method changes

If, in the AVAIL call, you have defined any origin or destination using coordinates, two additional data fields are required:

• <Name>
• <Address>

These fields may be sent in AVAIL (optional), but any of them that has not been provided in AVAIL will be mandatory in COMMIT for locations defined by coordinates.

Rules for <Name> and <Address>

AVAIL

• <Name> and <Address> are optional in AVAIL
• They only apply when the origin or destination is defined using GPS coordinates
• They are not used when searching by ID or IATA

COMMIT

• For locations defined by coordinates, both fields (<Name> and <Address>) must exist by the end of the COMMIT call, either:
  • Because they were already sent in AVAIL, or
  • Because they are provided in COMMIT if missing from AVAIL
• If either of these fields is missing, the booking cannot be confirmed

AVAIL vs COMMIT summary

Case	<Name> in AVAIL	<Address> in AVAIL	Must be sent in COMMIT?
Location by coordinates	Optional	Optional	Yes, if not previously sent
Location by ID (prefix L)	—	—	—
Location by Accommodation ID (prefix H)	—	—	—
Location by GIATA code (prefix G)	—	—	—
Location by IATA	—	—	—

In COMMIT, all fields (<Name> and/or <Address>) that were not previously provided in AVAIL must be sent for locations defined by coordinates.

Validation rules

The system enforces the following validation rules when processing transfer search requests with coordinates or IATA codes:

Identification rules

• For each origin and destination, you must provide exactly one identification method: LocationOriginID / LocationDestinationID (with prefix L, H, or G), IATA, or Coordinates.
• Sending more than one (e.g., both LocationOriginID and Coordinates) will return an error.
• Sending none will also return an error.

Coordinate rules

• Both <Latitude> and <Longitude> are required. Sending only one of them will return an error.
• Coordinates must be in decimal degrees (DD) format using the WGS84 standard.

Airport (IATA) rules

• When using an IATA code, the Type attribute must be A (Airport).
• When Type="A" is specified, an IATA code must be provided (coordinates are not accepted for airports).
• <Name> and <Address> cannot be sent alongside an IATA code. These fields only apply to coordinate-based locations.

Same origin/destination

• The system will reject requests where origin and destination resolve to the same location, whether identified by ID, IATA code, or coordinates.
• This includes cases where different coordinates resolve to the same internal location. Hotel-to-hotel transfers are the only exception.

tip

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

Examples available for testing in TEST

We include full examples that you can already execute in the TEST environment:

Search with hotel origin by coordinates + airport destination by IATA

AVAIL: Hotel origin (coordinates) → Airport destination (IATA)

<?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="2026-02-10" End="2026-02-17"/>
                <Occupations>
                    <AvailRequestV2Occupation>
                        <Type>ADL</Type>
                        <Age>30</Age>
                    </AvailRequestV2Occupation>
                </Occupations>

                    <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>

            </objRequest>
        </DestServicesAvailV2>
    </soap:Body>
</soap:Envelope>

Search with airport origin by ID + hotel destination by coordinates

AVAIL: Airport origin (ID) → Hotel destination (coordinates)

<?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="2026-02-10" End="2026-02-17"/>
                <Occupations>
                    <AvailRequestV2Occupation>
                        <Type>ADL</Type>
                        <Age>30</Age>
                    </AvailRequestV2Occupation>
                </Occupations>

                    <LocationOrigin>
                        <Name>Hotel Test</Name>
                        <Address>Address Origin Test</Address>
                        <Coordinates>
                            <Latitude>52.3657</Latitude>
                            <Longitude>4.88807</Longitude>
                        </Coordinates>
                        <IATA></IATA>
                    </LocationOrigin>

            </objRequest>
        </DestServicesAvailV2>
    </soap:Body>
</soap:Envelope>

Search with hotel origin by ID + airport destination by IATA

AVAIL: Hotel origin (ID) → Airport destination (IATA)

<?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="2026-02-10" End="2026-02-17"/>
                <Occupations>
                    <AvailRequestV2Occupation>
                        <Type>ADL</Type>
                        <Age>30</Age>
                    </AvailRequestV2Occupation>
                </Occupations>

                    <LocationDestination Type="A">
                        <Name></Name>
                        <Address></Address>
                        <Coordinates>
                            <Latitude></Latitude>
                            <Longitude></Longitude>
                        </Coordinates>
                        <IATA>AMS</IATA>
                    </LocationDestination>

            </objRequest>
        </DestServicesAvailV2>
    </soap:Body>
</soap:Envelope>

COMMIT example with coordinates

COMMIT: Including <Name> and <Address> for locations defined by coordinates

<?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="TEST_A_240409_01_2">

        <Concepts>
          <CommitRequestV2Concept>
            <ConceptBookingCode>67957</ConceptBookingCode>
            <Answers>
                <Answer Code="1126" RPH="1">55555555</Answer>
            </Answers>
            <Guests>
              <Guest>
                <GivenName>Name Test 1</GivenName>
                <Surname>Surname Test 1</Surname>
                <BirthDate>1983-01-21</BirthDate>
                <PhoneNumber>960000001</PhoneNumber>
              </Guest>
            </Guests>

          </CommitRequestV2Concept>
          <CommitRequestV2Concept>
            <ConceptBookingCode>67958</ConceptBookingCode>
            <Answers>
                <Answer Code="1126" RPH="1">55555555</Answer>
            </Answers>
            <Guests>
              <Guest>
                <GivenName>Name Test 2</GivenName>
                <Surname>Surname Test 2</Surname>
                <BirthDate>1983-01-21</BirthDate>
                <PhoneNumber>960000001</PhoneNumber>
              </Guest>
            </Guests>

          </CommitRequestV2Concept>
        </Concepts>
      </objRequest>
    </DestServicesCommitV2>
  </soap:Body>
</soap:Envelope>

Full technical documentation

All updated documentation is available in our APIs Documentation site