Flight price advice (preview)

This tool is in preview mode. Please contact support to request access.

Capability

flight_price_advice accepts a flight with its current price. Its planned outputs separate the current price’s position among comparable historical low fares from the risk of waiting one or three days. The development preview validates the request and returns the contract below. It does not search for live fares, create a price alert, book travel, or verify that the supplied quote is still available. Use price_monitoring for the existing price-monitoring capability.

Surface	Entry point
MCP	`flight_price_advice` on the development Builder MCP
REST	`POST /v1/flight_price_advice` on the development API
TypeScript SDK	`tools.flightPriceAdvice(input)` in the development build
CLI	`jinko flight-price-advice` in the development build, with the preview enabled

The preview is absent from production MCP discovery, production REST OpenAPI, and the default CLI help. Production and sandbox do not serve this endpoint.

Input

All fields except wait_days are required. Unknown fields are rejected.

Field	Type	Meaning
`origin`	string	Uppercase three-letter IATA city code. No automatic airport-to-city expansion.
`destination`	string	Uppercase three-letter IATA city code, different from `origin`.
`departure_date`	string	Real `YYYY-MM-DD` date strictly after today’s UTC date.
`trip_type`	`oneway` or `roundtrip`	Trip shape. The preview accepts both values; initial planned statistics cover one-way trips only.
`max_stops`	`0`, `1`, or `2`	Maximum stops. Initial planned statistics cover nonstop trips only.
`cabin_class`	string	`economy`, `premium_economy`, `business`, or `first`.
`current_price`	Amount	One adult’s total fare including taxes for the supplied trip, excluding optional paid extras.
`wait_days`	`1` or `3`	Waiting horizon in days. Defaults to `1`.

current_price uses { value, currency, decimal_places }. value is a positive safe integer, currency is a supported uppercase ISO 4217 currency code, and decimal_places must match that currency’s minor-unit precision. Divide value by 10 ** decimal_places to obtain the major-unit amount: 32000, USD, 2 means **

320**, not

32,000. Do not pass a base fare or a total for multiple passengers. Example request (use a future departure date):

{
  "origin": "NYC",
  "destination": "LAX",
  "departure_date": "2027-06-15",
  "trip_type": "oneway",
  "max_stops": 0,
  "cabin_class": "economy",
  "current_price": { "value": 32000, "currency": "USD", "decimal_places": 2 },
  "wait_days": 1
}

APEX is calculated by the server as the UTC calendar-day difference between the request date and departure date. There is no apex input and no required offer_token.

Call the development preview

Use development credentials with the development API. Install the development CLI release explicitly:

npm install -g @gojinko/cli@dev

The preview requires both the feature flag and a development or loopback API address. Production and sandbox addresses are rejected even when the flag is enabled.

JINKO_ENABLE_FLIGHT_PRICE_ADVICE=1 \
JINKO_API_BASE=https://api.dev.gojinko.com \
jinko flight-price-advice \
  --origin NYC --destination LAX --departure-date 2027-06-15 \
  --trip-type oneway --max-stops 0 --cabin-class economy \
  --current-price 32000 --currency USD --decimal-places 2 --wait-days 1

For REST, send the input JSON above to https://api.dev.gojinko.com/v1/flight_price_advice using the normal X-API-Key header. For MCP, connect to the development Builder endpoint https://jinko-e90ee33b.alpic.live/mcp and call flight_price_advice with the same JSON arguments. Keep credentials in your environment or credential store.

Output

Historical observation example

The offline analysis includes this observed price history for one LAX → NYC itinerary departing on September 10, 2026. The initial observation was on September 1 at 06:36:14 UTC, nine days before departure.

Observation	Price (NUC)	Change from initial price
Initial observation	317.200	—
September 2, 09:37:04 UTC — 27.01 hours later	376.400	+18.66%
September 4, 09:14:49 UTC — 74.64 hours later	424.410	+33.80%

These values come from the historical quote-pair dataset used in the September 29, 2026 offline experiment. They show what happened to this itinerary’s observed prices. The one-day and three-day comparisons use observation windows of 24–30 and 72–78 hours respectively. Fare conditions were not verified to remain identical across observations. NUC is the dataset’s normalized pricing unit. It cannot be supplied as the ISO currency in current_price. This example does not establish a typical price, a forecast probability, or a buy/wait recommendation. Those results still require the statistical computation described below.

Current preview response

A valid REST request returns HTTP 200. MCP returns the same object as structuredContent and JSON text. REST requires a validated jnk_ API key, supplied in X-API-Key or as Authorization: Bearer jnk_…. OAuth bearer tokens are not supported by this REST preview. MCP retains its existing authenticated connection. Validation errors remain errors. The following fields are fixed for this preview:

{
  "schema_version": "1.0",
  "status": "not_ready",
  "reason": "statistics_not_ready",
  "summary": "Price statistics are not ready. This development preview validates the request only; it cannot assess this price or recommend when to book.",
  "price_assessment": {
    "status": "unavailable",
    "reason_code": "statistics_not_ready",
    "label": null,
    "typical_price": null,
    "typical_range": null,
    "percentile": null,
    "difference_pct": null,
    "comparison_basis": "historical_comparable_low_fares",
    "evidence": null
  },
  "wait_assessment": {
    "status": "unavailable",
    "reason_code": "statistics_not_ready",
    "historical_reference": null
  },
  "recommendation": {
    "action": "no_clear_signal",
    "basis": null,
    "summary": "Statistics are not ready; no buy or wait recommendation is available."
  },
  "live_quotes_used": false
}

The response also includes context: the validated request with wait_days filled in, price_basis: "per_adult_total_including_tax", the request-processing timestamp evaluated_at, and the calculated integer apex_days. null means no result was calculated. not_ready does not mean a typical price, a flat future price, insufficient samples, or advice to wait. comparison_basis names the planned comparison; evidence: null confirms no historical comparison has been produced. evaluated_at is not the freshness of historical data.

Next phase

The price-level assessment will use comparable historical low fares from EVA’s intermediate quote data. The waiting assessment will reuse separately validated price-change statistics. Currency conversion, fare comparability, historical coverage, sample thresholds, and data freshness must be checked before returning numeric results. No EVA model inference or statistical result is used in this preview.

Getting started

Guides

Authentication

Connect

Concepts

Flight price advice (preview)

Capability

Input

Call the development preview

Output

Historical observation example

Current preview response

Next phase

​Capability

​Input

​Call the development preview

​Output

​Historical observation example

​Current preview response

​Next phase

Capability

Input

Call the development preview

Output

Historical observation example

Current preview response

Next phase