Felo API PlatformFelo API Platform
全部 DataForSEO 端點
v0.2.0-beta
OpenAPI 3.1.0

即時 Google 飯店搜尋任務

Felo API Support
MIT
伺服器:https://openapi.felo.ai
用戶端程式庫
Shell Curl

DataForSEO

​

SEO, search-engine results, keyword research, backlinks and AI visibility data.

DataForSEO 操作

即時 Google 飯店搜尋任務

​

在 Google Hotels 中搜尋符合查詢條件的飯店，可指定日期與入住人數。採用 DataForSEO 的信封結構：資料位於 tasks[0].result，結果狀態位於 tasks[0].status_code——被拒絕的請求仍會回傳 HTTP 200。可透過它找到資訊類端點所需的飯店 id；post_dataforseo_business_google_hotel_info_live 是詳細檢視。

計費參考

  • 計量方式：依回報的回應成本計量。
  • 參考請求估算：0.2428 美元。
  • 參考客戶倍率：1.0。不得對已結算的客戶金額再次套用。

僅供參考的中繼資料，並非帳戶報價、保證價格或消費上限。資源額度並非 Felo 額度。最終費用依 Felo 計費記錄為準。

請求本文
application/json
  • 類型: array (object | null)[]
    • adults
      類型: integer | null

      成人數
      選填欄位
      如果未指定此欄位，將使用預設值 2；
      注意，成人與兒童合計最多可指定 6 人
      範例：
      1

    • amenities
      類型: array string[] | null

      飯店設施
      選填欄位
      可使用此欄位指定不同的飯店設施
      範例：
      [
      "free_parking",
      "pets_allowed"
      ]

      可能的值：
      "air_conditioning",<br>"all_inclusive_available",<br>"bar",<br>"free_breakfast",<br>"fitness_center",<br>"kid_friendly",<br>"free_parking",<br>"pets_allowed",<br>"pool",<br>"restaurant",<br>"room_service",<br>"spa",<br>"free_wifi",<br>"parking",<br>"indoor_pool",<br>"outdoor_pool",<br>"wheelchair_accessible",<br>"beach_access"

    • check_in
      類型: string | null

      入住日期
      選填欄位
      如果未指定此欄位，預設使用明天的日期；
      日期格式："yyyy-mm-dd"
      範例：
      "2019-01-15"
      注意：該值不能早於今天的日期

    • check_out
      類型: string | null

      退房日期
      選填欄位
      如果未指定此欄位，我們的系統預設採用兩天後的日期；
      日期格式："yyyy-mm-dd"
      範例：
      "2019-01-15"
      注意：該值不能小於或等於 check_in；
      check_in 與 check_out 之間的範圍不能超過 30 天

    • children
      類型: array string[] | null

      兒童人數與年齡
      選填欄位
      如果未指定此欄位，搜尋將不包含兒童；
      兒童年齡可為 0 至 17；
      注意，成人與兒童合計最多可指定 6 人
      如需包含一名 14 歲兒童，請設定以下值：
      [14]
      如需包含一名 13 歲兒童和一名 8 歲兒童，請設定以下值：
      [13,8]

    • currency
      類型: string | null

      貨幣
      選填欄位
      範例：
      "USD"

    • depth
      類型: integer | null

      解析深度
      選填欄位
      Google Hotels 中的結果數量
      預設值：18 筆自然結果
      最大值：140
      注意：無論回應中是否包含付費列表，你的帳戶都將按每 18 筆自然結果計費；
      因此，如果 Google Hotels 傳回超過 18 筆結果，將解析深度設為高於 18 可能產生額外費用；
      如果指定深度高於回應中的結果數量，差額將自動退還至你的帳戶餘額

    • free_cancellation
      類型: boolean | null

      可免費取消的飯店
      選填欄位
      如需取得可免費取消預訂的飯店清單，請將此欄位設為 true
      預設值：false

    • is_vacation_rentals
      類型: boolean | null

      搜尋度假租賃房源
      選填欄位
      如需取得度假租賃房源清單而非飯店，請將此欄位設為 true
      預設值：false

    • keyword
      類型: string | null

      關鍵字
      選填欄位
      你指定的關鍵字用於搜尋飯店清單；
      如果不使用此欄位，我們將傳回在指定地點找到的飯店清單；
      在 keyword 欄位中最多可指定 700 個字元
      所有 %## 都會被解碼（另外，字元 ‘+’ 會解碼為空格）
      如果需要在 keyword 中使用 “%” 字元，請指定為 “%25”；
      注意：為獲得準確的搜尋結果，地點名稱會自動附加到關鍵字後

      有關 DataForSEO API 中 keyword 與 keywords 欄位的規則與限制，請參閱這篇 說明中心文章

    • language_code
      類型: string

      搜尋引擎語言代碼
      未指定 language_name 時為必填欄位
      如果使用此欄位，則無需指定 language_name
      可個別向 https://api.dataforseo.com/v3/business_data/google/languages 發出請求，取得可用語言及其 language_code 清單
      範例：
      en

    • language_name
      類型: string

      搜尋引擎語言全名
      未指定 language_code 時為必填欄位
      如果使用此欄位，則無需指定 language_code
      可個別向 https://api.dataforseo.com/v3/business_data/google/languages 發出請求，取得帶 language_name 的可用語言清單
      範例：
      English

    • location_code
      類型: integer

      搜尋引擎地點代碼
      未指定 location_name 或 location_coordinate 時為必填欄位
      如果使用此欄位，則無需指定 location_name 或 location_coordinate
      可個別向 https://api.dataforseo.com/v3/business_data/google/locations 發出請求，取得帶 location_code 的可用地點清單
      範例：
      2840

    • location_coordinate
      類型: string

      地點的 GPS 座標
      未指定 location_name 或 location_code 時為必填欄位
      如果使用此欄位，則無需指定 location_name 或 location_code
      location_coordinate 參數應以 "latitude,longitude" 格式指定
      "latitude" 與 "longitude" 的最大小數位數為 7
      注意：如果使用座標設定地點，搜尋將在最近的聚落進行
      範例：
      53.476225,-2.243572

    • location_name
      類型: string

      搜尋引擎地點全名
      未指定 location_code 或 location_coordinate 時為必填欄位
      如果使用此欄位，則無需指定 location_code 或 location_coordinate
      可個別向 https://api.dataforseo.com/v3/business_data/google/locations 發出請求，取得帶 location_name 的可用地點清單
      範例：
      London,England,United Kingdom
      注意：為獲得準確的搜尋結果，你指定的 location_name 將自動附加到關鍵字後

    • max_price
      類型: integer | null

      每晚最高價格
      選填欄位
      此值的貨幣取決於 currency 欄位
      範例：
      600

    • min_price
      類型: integer | null

      每晚最低價格
      選填欄位
      此值的貨幣取決於 currency 欄位
      範例：
      100

    • min_rating
      類型: number | null

      最低評分
      選填欄位
      可使用此欄位指定高於某一值的住客評分
      範例：
      2.5

    • search_this_area
      類型: boolean | null

      顯示目前顯示區域內的飯店
      選填欄位
      可取以下值：true、false
      預設值：true
      如果設為 false，將關閉 search_this_area 模式
      注意：如果關閉 search_this_area 模式，搜尋期間 location_name 將不會附加到 keyword 後
      可在我們的說明中心進一步瞭解此參數

    • sort_by
      類型: string | null

      結果排序參數
      選填欄位
      可使用此欄位對結果排序
      可能的排序類型：
      relevance – 依最相關排序
      lowest_price – 依最低價格排序
      highest_rating – 依最高評分排序
      most_reviewed – 依評論最多排序
      預設值：relevance

    • stars
      類型: array string[] | null

      飯店星級
      選填欄位
      如需僅取得 5 星級飯店清單，請將此欄位設為 [5]
      範例：
      [3,4,5]

    • tag
      類型: string | null

      使用者自訂任務識別碼
      選填欄位
      字元數上限為 255
      可使用此參數識別任務，並將其與結果對應
      可在回應的 data 物件中找到指定的 tag 值

回應
  • 200
    類型: object | null · Response36Afe1097B20_BusinessDataGoogleHotelSearchesLiveResponseInfo
    • cost
      類型: number | null 格式: double

      任務總費用，美元

    • status_code
      類型: integer | null

      一般狀態碼 完整回應碼清單請見此處

    • status_message
      類型: string | null

      一般資訊訊息 完整的一般資訊訊息清單請見此處

    • tasks
      類型: array (object | null)[] | null

      任務陣列

      • 類型: object | null · Response36Afe1097B20_BusinessDataGoogleHotelSearchesLiveTaskInfo
        • cost
          類型: number | null 格式: double

          任務總費用，美元

        • data
          類型: object | null

          包含你在 POST 請求中指定的相同參數

          • propertyName
            類型: object | null
        • id
          類型: string | null

          任務識別碼 我們系統中 UUID 格式的唯一任務識別碼

        • path
          類型: array (string | null)[] | null

          URL 路徑

        • result
          類型: array (object | null)[] | null

          結果陣列

          • check_url
            類型: string | null

            搜尋引擎結果的直接 URL
            可用來確認我們提供了準確的結果

          • datetime
            類型: string | null

            收到結果的日期與時間
            採用 UTC 格式：“yyyy-mm-dd hh-mm-ss +00:00”
            範例：
            2019-11-15 12:57:46 +00:00

          • items
            類型: array (object | null)[] | null

            遇到的項目類型
            items 陣列中出現的搜尋引擎結果類型；
            可能的項目類型：hotel_search_item

            • hotel_identifier
              類型: string | null

              飯店實體在 Google 搜尋中的唯一識別碼
              範例：
              CgoI-KWyzenM_MV3EAE

            • is_paid
              類型: boolean | null

              表示付費飯店資訊
              若為 true，相關的 hotel_search_item 是付費廣告
              若為 false，相關的 hotel_search_item 是自然飯店資訊

            • location
              類型: object | null · Response36Afe1097B20_GpsCoordinatesLocationInfo

              飯店位置的 GPS 座標

              • latitude
                類型: number | null

                飯店在 Google 地圖中的緯度座標
                範例：
                "latitude": 51.584091

              • longitude
                類型: number | null

                飯店在 Google 地圖中的經度座標
                範例：
                "longitude": -0.31365919999999997

            • overview_images
              類型: array (string | null)[] | null

              飯店的精選圖片

            • prices
              類型: object | null · Response36Afe1097B20_HotelPriceInfo

              飯店價格

              • check_in
                類型: string | null

                入住日期與時間
                UTC 格式：“yyyy-mm-dd hh-mm-ss +00:00”
                範例：
                2019-11-15 12:57:46 +00:00

              • check_out
                類型: string | null

                退房日期與時間
                UTC 格式：“yyyy-mm-dd hh-mm-ss +00:00”
                範例：
                2019-11-15 12:57:46 +00:00

              • currency
                類型: string | null

                價格貨幣
                預設套用 USD，除非在 POST 陣列中指定

              • discount_text
                類型: string | null

                所套用折扣的說明

              • items
                類型: array (object | null)[] | null

                遇到的項目類型
                items 陣列中出現的搜尋引擎結果類型；
                可能的項目類型：hotel_search_item

                • currency
                  類型: string | null

                  價格貨幣
                  預設套用 USD，除非在 POST 陣列中指定

                • domain
                  類型: string | null

                  第三方網域 帶有價格資訊的第三方網站頁面網域

                • free_cancellation_until
                  類型: string | null

                  可免費取消的截止日期 UTC 格式：“yyyy-mm-dd hh-mm-ss +00:00” 若所選日期不提供免費取消，則等於 null

                • is_paid
                  類型: boolean | null

                  表示付費飯店資訊
                  若為 true，相關的 hotel_search_item 是付費廣告
                  若為 false，相關的 hotel_search_item 是自然飯店資訊

                • offers
                  類型: array (object | null)[] | null

                  精選價格優惠

                  • currency
                    類型: string | null

                    價格貨幣
                    預設套用 USD，除非在 POST 陣列中指定

                  • free_cancellation_until
                    類型: string | null

                    可免費取消的截止日期 UTC 格式：“yyyy-mm-dd hh-mm-ss +00:00” 若所選日期不提供免費取消，則等於 null

                  • max_visitors
                    類型: integer | null

                    訪客人數上限 此價格優惠適用的最大訪客人數

                  • offer_images
                    類型: array (string | null)[] | null

                    價格優惠圖片 價格優惠中所展示圖片的 URL

                  • price
                    類型: number | null

                    每晚價格

                  • title
                    類型: string | null

                    飯店標題

                  • type
                    類型: string | null

                    元素類型

                  • url
                    類型: string | null

                    價格優惠的 URL 價格優惠所在網站頁面的 URL

                • official_site
                  類型: boolean | null
                • price
                  類型: number | null

                  每晚價格

                • title
                  類型: string | null

                  飯店標題

                • type
                  類型: string | null

                  元素類型

                • url
                  類型: string | null

                  第三方頁面 URL 帶有價格資訊的第三方網站頁面 URL

              • price
                類型: number | null

                每晚價格

              • price_without_discount
                類型: number | null 格式: int64

                未套用折扣的每晚完整價格

              • prices_by_dates
                類型: array (object | null)[] | null
                • check_in_date
                  類型: string | null
                • check_out_date
                  類型: string | null
                • currency
                  類型: string | null

                  價格貨幣
                  預設套用 USD，除非在 POST 陣列中指定

                • price
                  類型: number | null

                  每晚價格

              • visitors
                類型: integer | null

                此價格對應的飯店訪客人數

            • reviews
              類型: object | null · Response36Afe1097B20_HotelReviewInfo

              飯店評論與評分資訊

              • mentions
                類型: array (object | null)[] | null

                飯店提及
                依標準劃分的飯店評論相關資訊

                • negative_count
                  類型: integer | null 格式: int64

                  依準則的負面評論數

                • positive_count
                  類型: integer | null 格式: int64

                  依準則的正面評論數

                • positive_score
                  類型: number | null

                  依準則的正面分數

                • title
                  類型: string | null

                  已評估準則的標題

                • total_count
                  類型: integer | null 格式: int64

                  依準則的所有評論數

                • visible_by_default
                  類型: boolean | null

                  元素預設可見
                  表示評論元素是否預設可見

              • other_sites_reviews
                類型: array (object | null)[] | null

                第三方網站上的評論
                來自第三方網站的評論

                • rating
                  類型: object | null · Response36Afe1097B20_RatingInfo

                  評論中的評分
                  第三方網站上評論中包含的評分資訊

                  • rating_max
                    類型: integer | null

                    rating_type 的最大值

                  • rating_type
                    類型: string | null

                    評分類型 此處可以找到下列元素：Max5、Percents、CustomMax

                  • value
                    類型: number | null 格式: double

                    評分的值

                  • votes_count
                    類型: integer | null 格式: int64

                    回饋數量

                • review_text
                  類型: string | null

                  評論文字
                  評論的文字

                • title
                  類型: string | null

                  評論標題
                  包含評論最初出現的第三方網站名稱

                • url
                  類型: string | null

                  評論 URL
                  指向評論最初出現的第三方網站的 URL

              • rating_distribution
                類型: object | null

                依票數劃分的評分分佈
                1 到 5 分範圍內各評分對應的票數分佈

                • propertyName
                  類型: integer | null 格式: Int64
              • value
                類型: number | null

                根據顧客投票的飯店整體評分

              • votes_count
                類型: integer | null 格式: int64

                顧客投票數
                納入飯店評分計算的顧客投票數

            • stars
              類型: integer | null

              飯店星級評分
              1 到 5 星的星級評分

            • title
              類型: string | null

              飯店標題

            • type
              類型: string | null

              元素類型

          • items_count
            類型: integer | null 格式: int64

            項目類型
            items 陣列中的項目數

          • keyword
            類型: string | null

            POST 陣列中收到的關鍵字
            傳回的關鍵字已解碼 %##（加號字元 '+' 會解碼為空格字元）

          • language_code
            類型: string | null

            POST 陣列中的語言代碼

          • location_code
            類型: integer | null

            POST 陣列中的位置代碼

        • result_count
          類型: integer | null 格式: int64

          result 陣列中的元素數

        • status_code
          類型: integer | null

          任務的狀態碼 由 DataForSEO 產生，範圍如下：10000-60000 完整回應碼清單請見此處

        • status_message
          類型: string | null

          任務的資訊訊息 完整的一般資訊訊息清單請見此處

        • time
          類型: string | null

          執行時間，秒

    • tasks_count
      類型: integer | null 格式: int64

      tasks 陣列中的任務數

    • tasks_error
      類型: integer | null 格式: int64

      tasks 陣列中傳回錯誤的任務數

    • time
      類型: string | null

      總執行時間，秒

    • version
      類型: string | null

      API 的目前版本

    application/json
  • 400

    無法處理該要求。請檢查請求參數。

  • 401

    需要有效的 Felo API 金鑰。

  • 402

    由於未符合計費要求，要求無法繼續。

  • 403

    該帳戶無權執行此操作。

  • 429

    已達到要求或支出上限。

  • 502

    服務無法完成該要求。

  • 503

    API 或計費服務暫時無法使用。

  • 504

    服務在處理要求時逾時。

  • default

    錯誤回應；上游透傳回應可能採用供應商格式

    application/json
Request Example for post/v1/beta/dataforseo/business_data/google/hotel_searches/live
curl https://openapi.felo.ai/v1/beta/dataforseo/business_data/google/hotel_searches/live \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '[
  {
    "language_code": "en",
    "location_name": "New York,New York,United States",
    "keyword": "cheap hotel",
    "check_in": "2023-06-01",
    "check_out": "2023-06-30",
    "currency": "USD",
    "adults": 2,
    "children": [
      "14"
    ],
    "sort_by": "highest_rating",
    "priority": 2,
    "tag": "example"
  }
]'

{
  "version": null,
  "status_code": null,
  "status_message": null,
  "time": null,
  "cost": null,
  "tasks_count": null,
  "tasks_error": null,
  "tasks": [
    {
      "id": null,
      "status_code": null,
      "status_message": null,
      "time": null,
      "cost": null,
      "result_count": null,
      "path": [
        null
      ],
      "data": null,
      "result": [
        {
          "keyword": null,
          "location_code": null,
          "language_code": null,
          "check_url": null,
          "datetime": null,
          "items_count": null,
          "items": [
            {
              "type": null,
              "hotel_identifier": null,
              "title": null,
              "stars": null,
              "is_paid": null,
              "location": "[Max Depth Exceeded]",
              "reviews": "[Max Depth Exceeded]",
              "overview_images": [
                "[Max Depth Exceeded]"
              ],
              "prices": "[Max Depth Exceeded]"
            }
          ]
        }
      ]
    }
  ]
}

操作成功

Live Google Hotel Searches Tasks

需要協助嗎？