✈️ Flight Search Skill

Query real-time flights via the 51smart API (skill.flight.51smart.com). Supports one-way, round-trip, and price calendar.

Note: This skill calls the above public API directly via HTTP POST. No local scripts or authentication required. User data (city/date) is used solely for flight search.

Workflow

Parse Input → Extract origin, destination, dates, passengers, cabin class, trip type
Complete Missing Info → Ask the user if any required fields are missing
Call API → POST directly to https://skill.flight.51smart.com/api/search
Format Output → Display results in a clear, structured format

Step 1: Parse User Input

| Field | Description | Default | Required | |-------|-------------|---------|----------| | fromCity | IATA airport code of departure city | — | ✅ | | toCity | IATA airport code of destination city | — | ✅ | | fromDate | Departure date (YYYY-MM-DD) | — | ✅ | | returnDate | Return date (YYYY-MM-DD) | — | Required for round-trip | | adultNumber | Number of adults | 1 | — | | childNumber | Number of children | 0 | — | | cabinClass | E / B / F / P | E | — | | flightType | oneWay / roundTrip | oneWay | — |

Cabin Codes:

E = Economy
P = Premium Economy
B = Business
F = First

Step 2: City to IATA Code

China

| City | Code | City | Code | |------|------|------|------| | Beijing | PEK/PKX | Shanghai Hongqiao | SHA | | Shanghai Pudong | PVG | Guangzhou | CAN | | Shenzhen | SZX | Chengdu | CTU | | Hangzhou | HGH | Nanjing | NKG | | Wuhan | WUH | Xi'an | XIY | | Chongqing | CKG | Xiamen | XMN | | Kunming | KMG | Sanya | SYX | | Haikou | HAK | Qingdao | TAO | | Zhengzhou | CGO | Changsha | CSX | | Jinan | TNA | Harbin | HRB | | Shenyang | SHE | Dalian | DLC | | Tianjin | TSN | Hefei | HFE | | Guiyang | KWE | Nanning | NNG | | Urumqi | URC | Lhasa | LXA |

International

| City | Code | City | Code | |------|------|------|------| | Hong Kong | HKG | Taipei | TPE | | Macau | MFM | Tokyo Narita | NRT | | Tokyo Haneda | HND | Osaka | KIX | | Seoul | ICN | Busan | PUS | | Singapore | SIN | Bangkok Suvarnabhumi | BKK | | Bangkok Don Mueang | DMK | Kuala Lumpur | KUL | | Jakarta | CGK | Manila | MNL | | Sydney | SYD | Melbourne | MEL | | Dubai | DXB | Abu Dhabi | AUH | | London Heathrow | LHR | London Gatwick | LGW | | Paris | CDG | Frankfurt | FRA | | Amsterdam | AMS | Rome | FCO | | New York JFK | JFK | New York Newark | EWR | | Los Angeles | LAX | San Francisco | SFO | | Las Vegas | LAS | Chicago | ORD | | Vancouver | YVR | Toronto | YYZ |

For cities not listed above, infer the IATA code based on common conventions, or ask the user to confirm the full airport name.

Step 3: Call API

Send an HTTP POST request directly — no local scripts required.

Endpoint: POST https://skill.flight.51smart.com/api/search Content-Type: application/json Auth: Not required

One-way Request Example

{
  "adultNumber": 1,
  "cabinClass": "E",
  "childNumber": 0,
  "cid": "123456",
  "flightType": "oneWay",
  "flights": [
    {
      "fromCity": "PEK",
      "fromDate": "2026-03-15",
      "toCity": "SHA"
    }
  ]
}

Round-trip Request Example

{
  "adultNumber": 2,
  "cabinClass": "B",
  "childNumber": 1,
  "cid": "123456",
  "flightType": "roundTrip",
  "flights": [
    { "fromCity": "PEK", "fromDate": "2026-03-15", "toCity": "NRT" },
    { "fromCity": "NRT", "fromDate": "2026-03-22", "toCity": "PEK" }
  ]
}

Price Calendar

The price calendar is achieved by sending multiple one-way requests for consecutive dates and aggregating results.

Step 4: Format Output

One-way / Round-trip Results

✈️ Beijing (PEK) → Shanghai (SHA)
📅 Mar 15, 2026  |  Economy  |  Adult × 1

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 #  Flight      Depart→Arrive       Duration  Stops   Price (USD)  Baggage
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 1  UA1597      22:38→00:06(+1)     1h28m     Nonstop $81.86       1PC/23KG
 2  CA1234      09:00→11:20         2h20m     Nonstop $95.00       1PC/23KG
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
2 flights found
Lowest: $81.86 (before tax), incl. tax: $116.80

Price Calendar Results

📅 Price Calendar
✈️ Shanghai (SHA) → Los Angeles (LAX)  |  Economy

Date            Lowest          Flights
─────────────────────────────────────
2026-04-01      $520.00 ⭐       8
2026-04-02      $490.00 🏆 Best  6
2026-04-03      $535.00          7
2026-04-04      $510.00          5
2026-04-05      $580.00          6
─────────────────────────────────────
Recommended date: 2026-04-02 ($490.00)

Field Interpretation Rules

Total price incl. tax = price + tax (adult fare)
Multiple passengers = adult total × adultNumber + child total × childNumber
Stops = number of segments - 1; show stopover city when stopQuantity > 0
Baggage = baggages[].pieces + baggages[].weight; note "baggage not included" when freeBaggage: false
Limited seats = show ⚠️ "Only X seats left" when maxSeatsRemain ≤ 3

Key Response Fields

| Field | Description | |-------|-------------| | status | 0 = success | | message | "SUCCESS" indicates normal response | | routings[] | List of flight options | | routings[].prices[] | Prices by passenger type (ADT = Adult, CHD = Child) | | routings[].segments[] | Segment details (each stopover is a separate segment) | | routings[].rule.baggages[] | Free baggage allowance | | routings[].rule.freeBaggage | false = baggage must be purchased separately | | routings[].maxSeatsRemain | Remaining seats | | passengerType | ADT = Adult, CHD = Child |

Error Handling

| Scenario | Action | |----------|--------| | status != 0 or message != "SUCCESS" | Inform the user the query failed; suggest trying a different date | | routings is an empty list | Notify that no flights are available for this route/date | | Network timeout | Retry once; if it fails again, ask the user to try later | | Unrecognized city code | Ask the user to confirm the full city or airport name | | childNumber > adultNumber | Prompt: "Number of children cannot exceed the number of adults" |