Hostel World API

The Hostelworld API lets developers search hostels by city, retrieve full property profiles, check room availability with per-night price breakdowns, and paginate through guest reviews. Access ratings, facilities, cancellation policies, and dorm/private room pricing—ideal for travel apps, price comparison tools, and accommodation aggregators.

原始信息汇总

Hostel World API 数据集概述

基本信息

• API名称: Hostel World API
• 类别: Travel
• 提供商: kakoto
• 订阅者数量: 1
• API版本: 1.0.0 (current)
• 服务等级: 100%
• 延迟: 2433ms
• 测试覆盖率: 100%

订阅计划与定价

• BASIC: $0.00 / 月
• PRO: $15.00 / 月
• ULTRA: $49.00 / 月
• MEGA: $139.00 / 月

API概述

Hostelworld API 为开发者提供对全球旅舍和预算住宿数据的结构化访问。该API允许开发者按城市搜索旅舍、检索完整的物业资料、检查带有每夜价格细分的房间可用性，以及分页浏览住客评论。可访问的数据包括评分、设施、取消政策以及宿舍/私人房间价格。该API适用于旅行应用程序、价格比较工具和住宿聚合器。

端点详情

1. POST /hotel/get-by-url — 通过URL获取酒店详情

• 功能: 使用Hostelworld URL检索旅舍的完整物业信息。
• 必需输入字段: url (完整的Hostelworld旅舍URL，包含日期和住客参数)。
• 关键响应字段: id, name, type, city, address1/address2, latitude/longitude, description, overview, directions, rating (包含overall, staff, location, security, atmosphere, facilities, cleanliness, value_for_money), total_ratings, facilities, check_in, latest_check_out, property_prices, lowest_price_per_night, free_cancellation, cancellation_policy, payment_methods, deposit_percentage, images/images_gallery, reviews, group_information, max_number_of_guests_per_booking。

2. GET /hotel — 通过ID获取酒店详情

• 功能: 与/hotel/get-by-url等效，但接受结构化查询参数。
• 必需输入字段: hotel_id (物业ID), guests (住客数量), date_start (入住日期，格式为YYYY-MM-DD), num_nights (住宿夜数)。
• 响应结构: 与/hotel/get-by-url相同。

3. POST /hotel/listing-by-url — 通过搜索URL列出酒店

• 功能: 从Hostelworld城市搜索URL检索旅舍列表，包含房型、价格、评分和促销信息。
• 必需输入字段: url (完整的Hostelworld搜索URL)。
• 响应结构: 包含hotels数组和pagination对象。
• 列表中的关键酒店字段: id, name, type, address1, district, distance, overall_rating, rating_breakdown, rooms.dorms/rooms.privates, lowest_price_per_night, lowest_dorm_price_per_night, lowest_private_price_per_night, lowest_average_price_per_night, promotions, free_cancellation_available, free_cancellation_available_until, is_featured/is_promoted, hostelworld_recommends, categories, facilities。

4. GET /hotel/search — 按城市ID搜索酒店

• 功能: 使用结构化参数为特定城市搜索旅舍。
• 必需输入字段: city_id (城市ID), guests (住客数量), date_start (入住日期，格式为YYYY-MM-DD), num_nights (住宿夜数)。
• 响应格式: 与/hotel/listing-by-url相同 — 包含hotels数组和pagination对象。

5. POST /hotel/availability/get-by-url 和 GET /hotel/availability — 获取房间可用性

• 功能: 检索特定物业和日期范围内的实时房间可用性，包含每夜价格细分和价格计划选项。
• GET端点必需输入字段: hotel_id (物业ID), guests (住客数量), date_start (入住日期，格式为YYYY-MM-DD), num_nights (住宿夜数)。
• 关键可用性字段: rooms.dorms/rooms.privates, total_beds_available, rate_plans, total_price, price_breakdown, average_price_per_night, lowest_price_per_night, deposit_percentage, free_cancellation_available_until, cancellation_policies。

6. GET /hotel/review — 获取酒店评论

• 功能: 检索物业的分页住客评论，支持过滤和排序选项。
• 必需输入字段: hotel_id (物业ID), page (页码，从1开始)。
• 可选输入字段: sort (排序顺序: "-date" (最新), "date" (最旧), "rating" (最高评分), "-rating" (最低评分), "age-group"), all_languages (设置为true以包含所有语言的评论)。
• 评论对象字段: id, date, user (包含nickname, gender, nationality, number_of_reviews), notes, liked/disliked, rating (包含overall, staff, value, safety, location, atmosphere, facilities, cleanliness), recommended, language_code, is_machine_translated, owner_comment, group_information。
• 分页: 响应包含pagination对象，包含total_number_of_items, number_of_pages, next, prev。

响应与错误处理

• 成功响应格式: json { "statusCode": 200, "messageCode": "OK", "data": [ /* 结果对象数组 */ ] }

• 错误代码:

  • 400: 错误请求 — 检查参数或URL格式。
  • 404: 酒店或城市未找到。
  • 500: 内部服务器错误 — 短暂延迟后重试。

使用技巧与最佳实践

• 从URL提取ID: hotel_id和city_id可直接从Hostelworld URL中获取。
• 构建图片URL: 图片对象使用分割的prefix + suffix格式。拼接它们以形成完整URL。
• 比较可用性的价格计划: 可用性响应中的每个可用房间可能提供多个价格计划。在显示价格前，始终比较不同计划的total_price。
• 正确分页评论: 在迭代前检查pagination.number_of_pages。递增page参数直到最后一页。当没有更多页面时，next字段将为null。
• 错误处理: 针对404、400和500错误采取相应措施，例如检查参数有效性或使用指数退避重试。

法律声明

确保您对此API的使用符合Hostelworld的服务条款，然后再将收集的数据用于商业用途或重新分发。