Yahoo! Travel rooms API reference

JPY only. total_tax_included is the stay for every guest in the one room, with consumption tax included and the booking's own points used at once, as the site shows it; total_without_points is the same stay without them and list_total the plan before the site's own discount. price is the nightly average. Local accommodation and bathing taxes are paid at the hotel and never included. A full hotel answers availability: sold_out; dates not on sale are a 422. One room per quote.

Request

POSThttps://api.scrapercompany.com/v1/ota/yahoo_travel

Authenticate with your API key in the x-api-key header (see Authentication).

Run this request on your own API key from this page, with the values you type. Signed out? Sign in or get an API key.

Body

JSON object. Unknown fields are rejected with 422.

check_instring (date)required
First night of the stay, YYYY-MM-DD.
check_outstring (date) | null
Departure date. An alternative to nights — if both are given, this wins.
nightsintegerdefault 1min 1, max 14
Length of stay. Ignored when check_out is supplied.
adultsintegerdefault 2min 1, max 9
Adults in the one room quoted. Totals are for all of them.
hotel_nostringrequiredmin length 1, max length 300
Hotel number (eight digits, 00000065), or a hotel URL such as travel.yahoo.co.jp/00000065/.

Example request

curl -X POST "https://api.scrapercompany.com/v1/ota/yahoo_travel" \
  -H "x-api-key: $SCRAPERCOMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "check_in": "2026-12-25",
    "hotel_no": "00000065"
  }'

Response

200 — Yahoo! Travel rooms and plans (JPY, consumption tax included, points used). Metered responses carry x-credits-charged and x-credits-remaining headers (see credit headers).

200 response

{
  "search_parameters": {
    "engine": "yahoo_travel_property",
    "hotel_no": "00000065",
    "check_in_date": "2027-03-08",
    "check_out_date": "2027-03-10",
    "adults": 2
  },
  "property": {
    "property_id": "00000065",
    "name": "グランドニッコー東京 台場",
    "price_per_night": 31159,
    "total_tax_included": 62318,
    "currency": "JPY",
    "sold_out": false,
    "availability": "available",
    "is_soldout": false,
    "provenance": {
      "schema_version": 1,
      "observation_id": "rateobs_0123456789abcdef0123456789abcdef",
      "collection_id": "ratecol_0123456789abcdef0123456789abcdef",
      "observed_at": "2026-08-07T01:23:45.678Z",
      "source": "yahoo_travel",
      "source_kind": "ota_rate_plan",
      "source_property_id": "00000065",
      "requested_currency": "JPY",
      "returned_currency": "JPY",
      "price_basis": "consumption_tax_included_points_applied",
      "derivation": "normalized_upstream"
    },
    "rooms": [
      {
        "name": "【レギュラーフロア】スーペリアダブル",
        "room_code": "10199244",
        "room_type": "ダブル",
        "capacity": "1-2",
        "size_m2": 30,
        "available": true,
        "cheapest_price": 31159,
        "rate_plans": [
          {
            "plan_id": "11610342",
            "room_code": "10199244",
            "name": "【期間限定タイムセール】今だけの特別価格！ビジネスにもレジャーにもおすすめ／お部屋のみ",
            "price": 31159,
            "total_tax_included": 62318,
            "total_without_points": 73314,
            "list_total": 81458,
            "currency": "JPY",
            "meal": "食事なし",
            "remaining": 17,
            "points": 10996,
            "point_rate": 15,
            "rate_code": "11610342",
            "rate_category": "unknown",
            "meal_plan": "room_only",
            "rate_code_scope": "property",
            "provenance": {
              "schema_version": 1,
              "observation_id": "rateobs_0123456789abcdef0123456789abcdef",
              "collection_id": "ratecol_0123456789abcdef0123456789abcdef",
              "observed_at": "2026-08-07T01:23:45.678Z",
              "source": "yahoo_travel",
              "source_kind": "ota_rate_plan",
              "source_property_id": "00000065",
              "requested_currency": "JPY",
              "returned_currency": "JPY",
              "price_basis": "consumption_tax_included_points_applied",
              "derivation": "normalized_upstream",
              "upstream_rate_id": "11610342"
            }
          }
        ]
      }
    ]
  },
  "meta": {
    "source": "yahoo_travel",
    "nights": 2,
    "adults": 2,
    "elapsed_s": 0.62,
    "total_rate_plans": 66,
    "comparable_across_markets": false,
    "notes": "JPY only. Totals include consumption tax and use the booking's own points at once, as the site shows them; total_without_points is the same stay without them. Local accommodation and bathing taxes are paid at the hotel and are never included."
  }
}

Response fields

Fields marked required are always present; others appear when they apply.

search_parametersobjectrequired
Show 5 child fieldsHide child fields
- search_parameters.enginestringrequired
  One ofyahoo_travel_property
- search_parameters.hotel_nostringrequired
- search_parameters.check_in_datestring (date)required
- search_parameters.check_out_datestring (date)required
- search_parameters.adultsintegerrequired
propertyobjectrequired
Show 12 child fieldsHide child fields
- property.property_idstringrequired
  The hotel number.
- property.namestring | nullrequired
- property.price_per_nightnumber | nullrequired
  Cheapest plan's nightly average.
- property.total_tax_includedinteger | nullrequired
  Cheapest plan's whole stay.
- property.currencystringrequired
  One ofJPY
- property.sold_outbooleanrequired
- property.availabilitystringrequired
  One ofavailablesold_out
- property.is_soldoutboolean | nullrequired
- property.availability_reasonstring | nullrequired
- property.min_length_of_stayinteger | nullrequired
- property.provenanceobject | nullrequired
  Provenance of the cheapest priced row; null when nothing priced.
  Show 13 child fieldsHide child fields
  - property.provenance.schema_versionintegerrequired
    Provenance schema version (currently 1).
  - property.provenance.observation_idstringrequired
    Deterministic id of this price observation (rateobs_...).
  - property.provenance.collection_idstringrequired
    Id shared by every price from one upstream fetch (ratecol_...).
  - property.provenance.observed_atstringrequired
    UTC observation time, ISO-8601.
  - property.provenance.sourcestringrequired
    Upstream source, e.g. google_hotels_calendar.
  - property.provenance.source_kindstringrequired
    Kind of source, e.g. calendar, offer, ota_calendar, official.
  - property.provenance.source_property_idstringrequired
    Property identifier at the source.
  - property.provenance.requested_marketstring | nullrequired
  - property.provenance.requested_currencystring | nullrequired
  - property.provenance.returned_currencystring | nullrequired
  - property.provenance.price_basisstringrequired
    What the price represents, e.g. room_base_before_taxes_and_fees.
  - property.provenance.derivationstringrequired
    How the figure was derived, e.g. normalized_upstream.
  - property.provenance.upstream_rate_idstring | nullrequired
    Source-native rate/room id when available.
- property.roomsarray of objectrequired
  Show 8 child fieldsHide child fields
  - property.rooms[].room_typestring | nullrequired
    Room type, in Japanese.
  - property.rooms[].capacitystring | nullrequired
    Guests the room takes, e.g. 1-2.
  - property.rooms[].size_m2integer | nullrequired
    Room size in square metres.
  - property.rooms[].namestringrequired
  - property.rooms[].room_codestringrequired
  - property.rooms[].availablebooleanrequired
  - property.rooms[].cheapest_pricenumber | nullrequired
  - property.rooms[].rate_plansarray of objectrequired
metaobjectrequired
Show 9 child fieldsHide child fields
- meta.sourcestringrequired
  One ofyahoo_travel
- meta.collection_idstringrequired
- meta.observed_atstringrequired
- meta.nightsintegerrequired
- meta.adultsintegerrequired
- meta.elapsed_snumberrequired
- meta.total_rate_plansintegerrequired
- meta.comparable_across_marketsbooleanrequired
  Always false.
- meta.notesstringrequired

Errors

Errors return a JSON body with a detail field. Failed requests are not charged. See Errors for the full list and retry advice.

Status	Meaning	Retry?
`401`Unauthorized	Missing or invalid API key. `{"detail":"missing or invalid API key"}`	No, fix the request
`402`Payment Required	Not enough credits for this request: the account's credits mode is `enforce` (`mode` in `GET /v1/billing`) and the request costs more than the available credits. Nothing is run or charged. `{"detail":"insufficient credits: this request costs 5, 0 available. Credits renew 2026-11-01."}`	No, fix the request
`404`Not Found	The property, stay, job or record was not found. `{"detail":"job not found"}`	No, fix the request
`422`Unprocessable Content	Request validation failed. `detail` is a list of problems for schema errors, or a string for semantic checks performed by the endpoint. `{"detail":[{"loc":["body","name"],"msg":"Field required","type":"missing"}]}`	No, fix the request
`429`Too Many Requests	Too many requests: the key's requests-per-minute limit was exceeded, or (in `enforce` credits mode) the plan's concurrent-request limit. No rate-limit or Retry-After headers are sent; back off and retry. `{"detail":"rate limit 60/min exceeded"}`	Yes, with backoff
`503`Service Unavailable	Temporarily unavailable: a dependency of this endpoint is down, or the upstream source changed its contract. Retry later. `{"detail":"database unavailable: OperationalError"}`	Yes, with backoff

Try it

Press Try it above to run this request on your own key, with the values you type (sign in first). For a no-code walkthrough, use the workspace’s guided Try it.

Export your key: export SCRAPERCOMPANY_API_KEY=sk_... (no key yet? start a free trial).
Copy the cURL example above and run it in a terminal.

Credits

12 credits per successful call. Failed, blocked and empty results are free.

Request#

Body#

Example request#

Response#

Response fields#

Errors#

Try it#