Skip to navigation

Seat maps

Show the seat layout and move passengers to the seats they want
View as Markdown

Call OTA_AirSeatMapRQ to get the seat map for a segment of a booking. Use it to show travelers the coach layout, see which seats are free, and let them pick. Moving a passenger to a seat is then a change to the booking with OTA_AirBookModifyRQ.

Seat maps and seat changes work on paid bookings only

You can request a seat map, and change a seat, only after the booking is paid and before its updateTravellersTimeLimit passes. Seats on a segment that has departed or been cancelled cannot change. Outside that window the API answers with CHANGES_ARE_NOT_PERMITTED.

Get the map

Read the booking first with OTA_ReadRQ. The seat map request reuses three things from it: the segment as flightSegmentInfo, the booking’s travelers as airTravelers, and the W1 locator in bookingReferenceID. Name the travelers you want a map for in travelerRefNumberRPHs. Send one seatMapRequest per segment, so a round trip has two.

{
"version": "2.001",
"pos": {
"source": [
{
"isocurrency": "SAR",
"requestorID": { "id": "AGENT001", "name": "Sample Travel", "type": "5" },
"bookingChannel": { "type": "OTA" }
}
]
},
"seatMapRequests": {
"seatMapRequest": [
{
"flightSegmentInfo": {
"rph": "1",
"departureAirport": { "locationCode": "JXD" },
"arrivalAirport": { "locationCode": "MKX" },
"operatingAirline": { "code": "HHR", "flightNumber": "0141" },
"marketingAirline": { "code": "HHR" },
"flightNumber": "0141",
"departureDateTime": "2026-05-20T17:21:00.000+03:00",
"arrivalDateTime": "2026-05-20T17:55:00.000+03:00",
"resBookDesigCode": "Y",
"fareBasisCode": "ECOUMINOW",
"status": "30",
"tpaextensions": {
"seatDetails": [{ "coach": "006", "seat": "116", "seatType": "aisle" }]
}
},
"travelerRefNumberRPHs": ["1"]
}
]
},
"airTravelers": {
"airTraveler": [
{
"passengerTypeCode": "CTC",
"personName": { "givenName": ["BARAA"], "surname": "BUKHARI" },
"email": [{ "value": "contact@example.com" }]
},
{
"passengerTypeCode": "ADT",
"gender": "Male",
"personName": { "givenName": ["BARAA"], "surname": "BUKHARI" },
"document": [
{
"docID": "1234567890",
"docType": "5",
"docHolderNationality": "SA",
"birthDate": "1990-01-01",
"expireDate": "2030-12-31"
}
],
"travelerRefNumber": { "rph": "1" },
"flightSegmentRPHs": { "flightSegmentRPH": ["1"] }
}
]
},
"bookingReferenceID": [
{ "companyName": { "code": "W1" }, "type": "14", "id": "N6G2NW" }
]
}

The segment’s tpaextensions.seatDetails shows where the passenger sits now: the coach, the seat, and whether it is a window or aisle seat. Every segment a paid booking returns carries this block.

Read the map

The response holds one seatMapResponse per segment you asked for. Each one repeats the segment in flightSegmentInfo and lists the coaches in seatMapDetails[].cabinClass[]. A coach describes itself two ways: a flat availabilityList for a quick free-or-taken check, and rowInfo with the full detail of every seat for drawing the map.

{
"seatMapResponses": {
"seatMapResponse": [
{
"flightSegmentInfo": {
"rph": "1",
"departureAirport": { "locationCode": "JXD" },
"arrivalAirport": { "locationCode": "MKX" },
"operatingAirline": { "code": "HHR", "flightNumber": "0141" },
"departureDateTime": "2026-05-20T17:21:00.000+03:00",
"resBookDesigCode": "Y"
},
"seatMapDetails": [
{
"cabinClass": [
{
"availabilityList": [
{ "seatNumber": "142", "availableInd": false, "occupiedInd": true },
{ "seatNumber": "143", "availableInd": true, "occupiedInd": false }
],
"rowInfo": [
{
"rowNumber": 2,
"gridNumber": 2,
"cabinType": "T",
"seatInfo": [
{
"summary": { "seatNumber": "142", "rowNumber": 2, "availableInd": false, "occupiedInd": true },
"availability": { "value": "SEAT_OCCUPIED" },
"features": [{ "value": "WINDOW" }, { "value": "OTHER", "extension": "ForwardFacing" }],
"status": [{ "value": "BOOKED" }],
"columnNumber": 4
},
{
"summary": { "seatNumber": "143", "rowNumber": 2, "availableInd": true, "occupiedInd": false },
"availability": { "value": "SEAT_AVAILABLE" },
"features": [{ "value": "AISLE" }, { "value": "OTHER", "extension": "ForwardFacing" }],
"status": [{ "value": "AVAILABLE" }],
"columnNumber": 3
}
]
}
],
"zone": [
{ "id": "52730000060000", "code": "006", "name": "006", "description": "6", "totalSeatQty": 38, "type": "T" }
],
"columnSpan": 5,
"startingRow": "0",
"endingRow": "10"
}
]
}
],
"bookingReferenceID": [
{ "companyName": { "code": "W1" }, "type": "14", "id": "N6G2NW" }
]
}
]
}
}

What each seat tells you

FieldValuesMeaning
availability.valueSEAT_AVAILABLEFree to take.
SEAT_OCCUPIEDTaken by another passenger.
SEAT_RESERVEDHeld by the passenger you asked about.
status[].valueAVAILABLE, BOOKED, ACTIVEThe same three states from the seat’s side: free, booked by someone else, booked by this passenger.
features[].valueWINDOW, AISLE, OTHERWhere the seat sits. OTHER carries an extension of ForwardFacing or BackwardFacing.
columnNumbernumberThe seat’s column across the coach.

How a coach is laid out

FieldMeaning
zone[]The coach: its id, code, name, description, totalSeatQty, and type.
cabinType and zone[].typeT is Economy, P is Business.
columnSpanHow many columns the map has.
startingRow and endingRowThe first and last row of the map.
rowInfo[].gridNumberThe row’s position on the grid.

Draw the grid from columnSpan and the row range, place each seat by rowNumber and columnNumber, and colour it from availability. Only offer a seat whose availability is SEAT_AVAILABLE.

Change a seat

Picking a seat is a change to the booking, not part of the seat map call. Send an OTA_AirBookModifyRQ with modificationType 5. Put the seat request in travelerInfo.specialReqDetails, and pass the full booking in airReservation as you read it back with OTA_ReadRQ.

{
"version": "2.001",
"pos": {
"source": [
{
"isoCurrency": "SAR",
"requestorID": { "id": "AGENT001", "name": "Sample Travel", "type": "5" },
"bookingChannel": { "type": "OTA" }
}
]
},
"airReservation": {
"bookingReferenceID": [
{ "companyName": { "code": "W1" }, "type": "14", "id": "N6G2NW" },
{ "companyName": { "code": "HHR" }, "type": "14", "id": "CB0255134" }
]
},
"airBookModifyRQ": {
"modificationType": "5",
"travelerInfo": {
"specialReqDetails": [
{
"seatRequests": {
"seatRequest": [
{
"flightRefNumberRPHList": ["1"],
"travelerRefNumberRPHList": ["1"],
"seatNumber": "143"
}
]
}
}
]
}
}
}

Each seatRequest names the segment, the traveler, and the seat:

FieldWhat it points at
flightRefNumberRPHListThe segment to change the seat on.
travelerRefNumberRPHListThe traveler getting the seat.
seatNumberThe seat you chose from the map.

airReservation here is the booking you get back from reading it; send that object as-is with your seat request added. The response returns the booking with the segment’s seatDetails updated to the new coach and seat, and the railway sends the passenger a ticket update notification.

When a seat change is refused

ErrorWhy
CHANGES_ARE_NOT_PERMITTEDThe booking is not paid yet, its updateTravellersTimeLimit has passed, or the segment has departed or been cancelled.
SYSTEM_ERRORThe railway could not process the change. Try again, and give support the correlationId if it keeps failing.

For the full seat-change payload, see the GO7 seat map and modify-booking pages. Updating other passenger details works the same way, through Updating passengers.