Designing a Cross-Border Airport Transfer Checklist as Structured Data

Gavin gui — Fri, 11 Sep 2026 08:23:48 +0000

Travel logistics look simple until one missing field breaks the plan. A destination such as “Shenzhen” is not enough for a driver, dispatcher, or booking form. The useful design problem is to turn a human request into structured data that can be validated before a vehicle is assigned.

This post uses a Hong Kong Airport to Shenzhen or Dongguan transfer as a practical example. CrossBorderHK operates the referenced service; this is an engineering-oriented adaptation, not a neutral price comparison. I used AI assistance for outlining and copy editing, and the operator must verify current operational details before publishing or using the data.

1. Model the request before calculating a quote

A minimum request should capture:

flight date and number
airport pickup location
exact destination address
city district or Dongguan township
passengers and children
luggage dimensions and unusual items
extra stops
return or waiting requirements
accessibility and child-seat needs

A small JSON object is easier to validate than a paragraph copied from a chat message:

{
  "arrival": { "date": "2026-10-18", "flight": "CX000", "airport": "HKG" },
  "destination": { "city": "Shenzhen", "district": "Nanshan", "address": "Hotel name and entrance" },
  "passengers": 4,
  "children": 1,
  "luggage": [{ "count": 4, "size": "24in" }],
  "stops": [],
  "needs": ["child-seat"]
}

For Dongguan, replace district with township and include the industrial park or factory gate. This prevents a city-level quote from hiding the last-mile problem.

2. Validate fields at the edge

Validation should happen before dispatch. A lightweight TypeScript example:

type TransferRequest = {
  arrival: { date: string; flight: string; airport: "HKG" };
  destination: { city: "Shenzhen" | "Dongguan"; district?: string; township?: string; address: string };
  passengers: number;
  children: number;
  luggage: { count: number; size?: string }[];
  stops: string[];
};

function validate(r: TransferRequest) {
  if (!r.arrival.flight || !r.destination.address) throw new Error("Flight and exact address are required");
  if (r.destination.city === "Shenzhen" && !r.destination.district) throw new Error("Add the Shenzhen district");
  if (r.destination.city === "Dongguan" && !r.destination.township) throw new Error("Add the Dongguan township");
  if (r.passengers < 1 || r.passengers > 6) throw new Error("Check vehicle passenger capacity");
}

The six-passenger limit reflects the normal Alphard arrangement described by the operator: seven seats including the driver. Keep this rule in configuration so the UI and dispatch service share one source of truth.

3. Keep price and route assumptions explicit

A quote object should separate a published reference value from a confirmed booking:

{
  "currency": "RMB",
  "referenceFare": 800,
  "destinationScope": "listed Shenzhen districts",
  "includes": ["driver", "fuel", "standard tolls"],
  "requiresConfirmation": ["waiting", "night surcharge", "extra stops", "border procedure"],
  "status": "reference"
}

The published Hong Kong Airport to Shenzhen reference starts at RMB 800 / HKD 930. The listed Hong Kong to Dongguan route starts at RMB 1,200 / HKD 1,400 for some townships. Treat both as starting references. The final address, date, vehicle, waiting, and route conditions still need written confirmation.

Avoid representing border behavior as a deterministic API response. Passenger and luggage procedures can depend on permits, checkpoint, documents, lane, and on-site officer instructions. Store the planned procedure together with a visible uncertainty note.

4. Generate a human-readable enquiry

The last step is a message a traveler can review:

Please quote a private transfer from HKG to [district/township and exact address]. Flight: [number/date]. Passengers: [count, children]. Luggage: [count and dimensions]. Stops: [list]. Please confirm total fare and currency, inclusions, waiting and overtime rules, cancellation terms, and planned border procedure.

This exposes assumptions before payment and gives a dispatcher enough context to correct the data instead of guessing.

5. Test failure paths

A useful test matrix includes:

Flight delay after the included waiting period.
Six passengers with oversized luggage.
A Dongguan request with two factory stops.
A midnight arrival requiring a different crossing plan.
An address change after booking.
A checkpoint instruction that requires passengers to leave the vehicle.

The test should verify that the interface asks for clarification, preserves the original request, and never silently converts a reference fare or estimated time into a guarantee.

Structured data does not remove uncertainty from cross-border travel. It makes the uncertainty visible early enough for a traveler, dispatcher, and driver to act on it.