# XML to Demand API v3.1 field mapping guide

**This guide explains how data returned by the legacy XML Car API maps to the Car Rental endpoints in Demand API v3.1. Use it to redesign your integration flows, update data handling, and understand how information is distributed across endpoints.**

## Demand API v3.1 overview

The Car Rental endpoints included in Demand API v3.1 support the following traveller flows:

* [Content-only integrations](/demand/docs/development-guide/application-flows/content-only).
* [Search, look, and redirect integrations](/demand/docs/development-guide/application-flows/search-look-redirect).
* Reporting and loyalty flows.


Unlike the legacy XML API, Demand API separates static and dynamic data across multiple endpoints. As a result, information previously returned in a single `SearchRS` response is now distributed across dedicated resources such as:

* /cars/search
* /cars/details
* /cars/depots
* /cars/suppliers
* /cars/depots/reviews/scores


This guide helps you understand how XML fields map to the new API structure.

## Main migration changes

Migrating from XML requires several architectural and implementation changes, including:

✅ Replacing XML with JSON.
✅ Moving from a single search response to multiple modular endpoints.
✅ Implementing Bearer token authentication.
✅ Storing static resources such as depots and suppliers.
✅ Handling paginated responses.
✅ Updating booking and post-booking flows.

Demand API v3.1 does not support end-to-end booking flows.
If you require booking capabilities through the API, consider implementing Demand API v3.2 instead. See XML to v3.2 Migration guide.

## Mapping overview

#### Car details

In the XML API, vehicle specifications were embedded directly in the `SearchRS` response.

In Demand API v3.1:

* /cars/search → returns high-level search results and car IDs.
* /cars/details → returns detailed vehicle specifications for each car ID.


This separation improves performance and enables better storing strategies.

XML API
```XML
<MatchList>
  <Match>
    <Vehicle 
      id="728723191" 
      propositionType="BR" 
      automatic="Manual" 
      aircon="Yes" 
      airbag="true" 
      petrol="N/A" 
      group="MBMR" 
      doors="2" 
      seats="4" 
      bigSuitcase="1" 
      smallSuitcase="1" 
      suitcases="N/A" 
      fuelPolicy="1" 
      cmaCompliant="true" 
      insurancePkg="I" 
      display="true" 
      order="0" 
      freeCancellation="true" 
      unlimitedMileage="false">
      
      <Name>Fiat 500</Name>
      <ImageURL>https://cdn.rcstatic.com/images/car_images/web/fiat/500_lrg.jpg</ImageURL>
      <LargeImageURL>https://cdn.rcstatic.com/images/car_images/web/fiat/500_lrg.jpg</LargeImageURL>
    </Vehicle>
  </Match>
</MatchList>
```

Demand API v3.1
1. Use the [car/search endoint](/demand/docs/open-api/demand-api/cars/search) endpoint to retrieve available car IDs:


```json
{
  "request_id": "01h00fr9y7qkbxtc6kyv97j49z",
  "data": [
    {
      "car": 122655,
      "policies": {
        "cancellation": {
          "type": "free_cancellation",
          "details": {
            "context": "before_pickup",
            "duration": "P7D"
          }
        }
      }
    }
  ]
}
```

1. Use the [/cars/details endpoint](/demand/docs/open-api/demand-api/cars/details) to return the full car details associated to each car `id`.


```json
{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": [
    {
      "id": 122655,
      "capacity": {
        "bags": {
          "large": 1,
          "small": 1
        },
        "doors": "4/2",
        "seats": "4+2"
      },
      "features": [
        "air_conditioning",
        "all_wheel_drive"
      ],
      "image": "https://example.com/image.jpg",
      "make": "hyundai",
      "model": "elantra",
      "specification": {
        "code": "ECAR",
        "description": "economy",
        "fuel": "petrol",
        "transmission": "automatic"
      },
      "supplier": 423
    }
  ],
  "metadata": {
    "next_page": null
  }
}
```

#### Migration notes

* Vehicle specifications are no longer embedded in search results.
* You must perform an additional request to retrieve full vehicle details.
* Vehicle and supplier data can be stored to reduce repeated API calls.


### Policies (deposit, excess, fuel, mileage)

In the XML API, policy-related information was spread across multiple nested structures.

In Demand API v3.1, these values are grouped under the policies object returned by [cars/search](/demand/docs/open-api/demand-api/cars/search).

#### Deposit and damage_excess

XML API
```XML
</Vehicle>
<Fees>
  <DepositExcessFees>
    <TheftExcess 
      amount="1500.0" 
      currency="GBP" 
      taxIncluded="true" />
    <DamageExcess 
      amount="1500.0" 
      currency="GBP" 
      taxIncluded="true" />
    <Deposit 
      amount="1500.0"
```

Demand API v3.1
```json
{
  "request_id": "01jwqr8qday6ttydkgbyvcca5v",
  "data": [
    {
      "car": 221868,
      "deal": null,
      "policies": {
        "cancellation": {
          "type": "free_cancellation",
          "details": {
            "context": "before_pickup",
            "duration": "PT48H"
          }
        },
        "damage_excess": 950,
        "deposit": 700,
        "payment": {
          "timing": "pay_now"
        },
        "fuel": "return_same",
        "mileage": {...},
        "theft_excess": 950
      },
      "price": {
        "currency": "EUR",
        "total": 172.93,
        "extra_charges": []
      },
      "route": {
        "dropoff": {
          "depot": 249276
        },
        "pickup": {
          "depot": 249276
        }
      },
      "supplier": 227,
      "url": {
        "app": "booking://search?affiliate_id=956509&driver_age=36&do_time=2025-12-10T11:05&do_loc_name=Amsterdam%20-%20Ruysdaelkade&pu_time=2025-12-05T11:05&pu_loc_name=Amsterdam%20-%20Ruysdaelkade&expand_search=false",
        "web": "https://cars.booking.com/search-results?vehicleId=769351076&vehicleInfo.vehicle.id=769351076&aid=956509&prefcurrency=EUR&preflang=en&driversAge=36&cor=nl&doHour=11&doMinute=5&doDay=10&doMonth=12&doYear=2025&dropLocationName=Amsterdam%20-%20Ruysdaelkade&puHour=11&puMinute=5&puDay=5&puMonth=12&puYear=2025&locationName=Amsterdam%20-%20Ruysdaelkade"
      }
```

#### Migration notes

* Related policy information is now consolidated into a single policies object.
* Payment timing is now explicitly represented through `payment.timing`.
* Fuel and mileage policies follow standardised enum-based values.


#### Fuel and mileage policies

Mileage and fuel information are returned directly in the [cars/search](/demand/docs/open-api/demand-api/cars/search) response in Demand v3.1.

XML API
```XML
<FuelPolicy type="RETURN_SAME" />
<KnownFees>
  <Fee 
    feeTypeName="MILEAGE" 
    alwaysPayable="false" 
    amount="0.5" 
    currency="GBP" 
    taxIncluded="true" 
    perDuration="rental" 
    feeDistance="1.0" 
    distance="700.0" 
    iskM="false" 
    unlimited="false" />
</KnownFees>
</Fees>
```

Demand API v3.1
```json
{
  "request_id": "01h00fr9y7qkbxtc6kyv97j49z",
  "data": [
    {
      "car": 122655,
      "policies": {...}
        },
        "fuel": "return_same",
        "mileage": {
          "distance": 200,
          "distance_unit": "kilometers",
          "fee": 12.54,
          "type": "limited"
        },
...
```

#### Migration notes

* Fuel policies now use standardised enum values.
* Mileage restrictions are grouped into a dedicated mileage object.
* Units are returned explicitly using `distance_unit`.


#### Pricing

In the XML API, pricing information included several intermediary pricing fields.

Demand API v3.1 simplifies this structure and returns traveller-facing pricing directly.

XML API
```xml
<Price 
  currency="EUR" 
  baseCurrency="GBP" 
  basePrice="465.8" 
  commission="0.00" 
  discount="0.00" 
  driveAwayPrice="563.92" 
  quoteAllowed="yes" 
  creditCardRequired="false">
  563.92
</Price>
```

Demand API v3.1
```json
{
  "request_id": "01h00fr9y7qkbxtc6kyv97j49z",
  "data": [
    {
      "car": 122655,
      "policies": {...}
        },
        "fuel": "return_same",
        "mileage": {...},
        "payment": {...}
      },
      "price": {
        "total": "50.00",
        "currency": "EUR"
      },
...
```

#### Migration notes

* Pricing is simplified compared to XML responses.
* Base pricing and commission breakdowns are no longer returned.
* The `price.total` value represents the traveller-facing total amount.


#### Depot data

In the XML API, pickup and drop-off location details were embedded directly in the search response.

In Demand API v3.1:

* /cars/search returns depot IDs.
* /cars/depots returns detailed depot information.


XML API
```XML
<Route>
  <PickUp>
    <Location 
      id="4608557" 
      locationId="37766" 
      locCode="LHR" 
      locName="London Heathrow Airport" 
      onAirport="no" />
  </PickUp>
  <DropOff>
    <Location 
      id="4608557" 
      locationId="37766" 
      locCode="LHR" 
      locName="London Heathrow Airport" 
      onAirport="no" />
  </DropOff>
</Route>
```

Demand API v3.1
Find the `depot` ID within the `route.dropoff` and `route.pickup` fields in the search response.

```json
{
  "request_id": "01h00fr9y7qkbxtc6kyv97j49z",
  "data": [
    {
      "car": 122655,
      "policies": {...}
        },
        "fuel": "return_same",
        "mileage": {...},
        "payment": {...}
      },
      "price": {...},
      "route": {
        "dropoff": {
          "depot": 112314
        },
        "pickup": {
          "depot": 112314
        }
      },
...
```

Use the [/cars/depots](/demand/docs/open-api/demand-api/cars/depots) endpoint to retrieve:

* Depot location information.
* Coordinates.
* Pickup instructions.
* Drop-off instructions.


#### Migration notes

* Depot information is now normalised and returned through dedicated endpoints.
* Integrations must join data using depot IDs.
* Caching depot information is strongly recommended.


#### Supplier data

Supplier information is no longer embedded in search responses.
Instead:

* /cars/search returns supplier IDs.
* /cars/suppliers returns supplier metadata.


XML API
```XML
<Supplier 
  long="-0.39796924" 
  lat="51.47040086" 
  dropOffLong="-0.39796924" 
  dropOffLat="51.47040086" 
  address="Vista Centre Salisbury Road, Cranford, Hounslow, London, UK, TW4 6JQ" 
  dropOffAddress="Vista Centre Salisbury Road, Cranford, Hounslow, London, UK, TW4 6JQ&quot;" 
  small_logo="https://cdn2.rcstatic.com/images/suppliers/wrp/flat/1463_logo_lrg.gif" 
  locType="Off Airport - Shuttle Service" 
  supplierName="Surprice" 
  pickUpInstructions="Please call 00443300949033 on arrival to arrange the shuttle service. Then, follow the signs to the Short Stay Car Park and wait at the corresponding level. T2: Level 4, lift area near row H. T3: Level 3, lift area near row A. T4: Level 2, lift area near row E. T5: Level 1, lift area near row R." 
  dropOffInstructions="Please call 00443300949033 on arrival to arrange the shuttle service. Then, follow the signs to the Short Stay Car Park and wait at the corresponding level. T2: Level 4, lift area near row H. T3: Level 3, lift area near row A. T4: Level 2, lift area near row E. T5: Level 1, lift area near row R." />
```

Demand API v3.1
Use the [/cars/suppliers](/demand/docs/open-api/demand-api/cars/suppliers) endpoint:

```json
{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": [
    {
      "id": 62,
      "name": "Budget",
      "logo": "https://example.com/path_to_the_logo.jpeg"
    }
  ],
  "metadata": {
    "next_page": null,
    "total_results": 1
  }
}
```

#### Migration notes

* Supplier information is now fully decoupled from search results.
* Supplier IDs are stable identifiers that should be cached.
* Depot-specific operational information is available through /cars/depots.


#### Review and scores

Depot review scores are now retrieved through a dedicated endpoint.

XML API
```XML
<![CDATA[Surprice (Flex)]]>
</Supplier>

<Ratings>
  <Average>7.1</Average>
  <AverageText>Very good</AverageText>
  <NumRatings>126</NumRatings>
  <ValForMoney>6.7</ValForMoney>
  <Efficiency>7.8</Efficiency>
  <CollectTime>7.3</CollectTime>
  <DropOffTime>8.2</DropOffTime>
  <Cleanliness>7.5</Cleanliness>
  <Condition>5.8</Condition>
  <Locating>7.5</Locating>
</Ratings>
```

Demand API v3.1
Use the [/cars/depots/reviews/scores endpoint](/demand/docs/open-api/demand-api/cars/depots/reviews/scores) to return the depot score breakdown together with the overall number of reviews and score:

```json
{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": [
    {
      "id": 5944,
      "breakdown": {
        "cleanliness": {
          "score": 8.7
        },
        "condition": {
          "score": 8.7
        },
        "drop_off_speed": {
          "score": 8.7
        },
        "friendliness": {
          "score": null
        },
        "likeliness_rent_again": {
          "score": 8.7
        },
        "location": {
          "score": 8.7
        },
        "pick_up_speed": {
          "score": 8.7
        },
        "value_for_money": {
          "score": 8.7
        }
      },
      "number_of_reviews": 105,
      "score": 9.1
    }
  ],
  "metadata": {
    "next_page": null
  }
}
```

#### Migration notes

* Review information is now depot-specific.
* Score breakdowns are more granular and structured.
* Some categories may return `null` if data is unavailable.


#### Clickout URLs

The XML API returned redirect URLs pointing to Rentalcars.com.

Demand API v3.1 now returns Booking.com Cars URLs for both web and app experiences.

XML API
```xml
<ForwardURL>https:/rentalcars.com/SearchResults.do......</ForwardURL>
```

Demand API v3.1
Find the `url` for both web and app within the [/search endpoint](/demand/docs/open-api/demand-api/cars/search) response:

```json
{
  "url": {
    "app": "booking://search?affiliate_id=956509&driver_age=21&do_time=2025-11-09T12:00&pu_time=2025-11-02T12:00&do_loc_iata=CDG&pu_loc_iata=CDG",
    "web": "https://cars.booking.com/search-results?vehicleId=737843316&aid=956509&prefcurrency=EUR&preflang=en"
  }
}
```

#### Migration notes

* Redirect URLs now point to Booking.com Cars.
* Affiliate attribution is automatically included through the `aid` parameter.
* Both app and web redirect URLs are returned.


## Testing your integration

Demand API does not currently provide a dedicated sandbox environment for Car Rentals.

Recommended testing approach:

* Use production credentials.
* Test with controlled traffic.
* Coordinate with your Account Manager if needed.


## Migration Checklist

| Checklist |
|  --- |
| ☑ | Generate API key and Affiliate ID. |
| ☑ | Replace XML authentication with Bearer token authentication. |
| ☑ | Integrate the new modular endpoints (search, details, common/supplier, etc.) |
| ☑ | Implement storing data for static resources. |
| ☑ | Implement label tracking where applicable. |
| ☑ | Update error handling to support HTTP status codes and structured error responses. |


## Summary

Migrating from the XML API to Demand API v3.1 requires a shift from monolithic XML responses to modular JSON-based endpoints.

Key migration changes include:

* Moving from XML to JSON.
* Handling multi-endpoint workflows.
* Implementing caching strategies.
* Supporting pagination.
* Updating authentication and attribution logic.


By adapting your integration to these patterns, you can build a more scalable and maintainable Car Rentals integration using Demand API v3.1.

## Next steps

Curious to know more?
* Explore the [Car rental Quick guide](/demand/docs/cars/cars-quick-guide) for an end-to-end integration walkthrough.
* See the [Error handling documentation](/demand/docs/support/error-handling/about-errors) for implementation guidance.
* Check the [Car rental API Collection section](/demand/docs/cars/overview) for best practices and use cases.
* Refer to the [Cars API reference](/demand/docs/open-api/demand-api/cars) for endpoint specifications.