Search live hotel inventory and rates
curl --request POST \
--url https://api.gojinko.com/v1/hotel_search \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"next_handle": "hp_example_2"
}
'import requests
url = "https://api.gojinko.com/v1/hotel_search"
payload = { "next_handle": "hp_example_2" }
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({next_handle: 'hp_example_2'})
};
fetch('https://api.gojinko.com/v1/hotel_search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.gojinko.com/v1/hotel_search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'next_handle' => 'hp_example_2'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.gojinko.com/v1/hotel_search"
payload := strings.NewReader("{\n \"next_handle\": \"hp_example_2\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.gojinko.com/v1/hotel_search")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"next_handle\": \"hp_example_2\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.gojinko.com/v1/hotel_search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"next_handle\": \"hp_example_2\"\n}"
response = http.request(request)
puts response.read_body{
"hotels": [
{
"hotel_id": "lp1d2c3",
"hotel_ref": "<string>",
"name": "Hôtel Le Marais",
"address": "12 Rue de Rivoli",
"city": "Paris",
"country": "fr",
"star_rating": 4,
"category": "4 KEYS",
"lodging_type": "Aparthotel",
"rating": 8.6,
"review_count": 1243,
"main_photo": "https://images.example.com/hotels/main.jpg",
"thumbnail": "https://images.example.com/hotels/thumb.jpg",
"latitude": 48.8566,
"longitude": 2.3522,
"distance_km": 1,
"recommendation_score": 0.5,
"intent_match_probability": 0.5,
"intent_confidence": 0.5,
"intent_evidence_status": "matched",
"intent_facts": {
"source": "hotel_catalog",
"name": "<string>",
"description": "<string>",
"facility_labels": [
"<string>"
],
"name_truncated": true,
"description_truncated": true,
"facility_labels_truncated": true,
"omitted_facts_status": "unknown"
},
"rooms": [
{
"room_id": "rm_1",
"room_name": "Superior Double",
"description": "<string>",
"requested_occupancy": 2,
"room_capacity": 2,
"max_occupancy": 2,
"images": [
"<string>"
],
"amenities": [
"<string>"
],
"beds": [
{
"bed_type": "<string>",
"count": 2
}
],
"rates": [
{
"offer_id": "htl_2d67a7441c60e5de",
"board_type": "RO",
"board_name": "Room Only",
"total_amount": 1818.4,
"total_amount_display": "EUR 606.13",
"currency": "EUR",
"total_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"is_refundable": false,
"free_cancellation_until": "2026-08-18T10:00:00+02:00",
"cancellation_schedule": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"taxes_breakdown": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"payment_types": [
"pay_now"
],
"promotions": [
{
"code": "<string>",
"name": "<string>",
"remark": "<string>"
}
],
"booking_scope": "room_bundle",
"num_rooms": 2,
"rooms": [
{
"occupancy_number": 1,
"occupancy": {
"adults": 2,
"children_ages": [
8
]
},
"room_id": "<string>",
"mapped_room_id": 123,
"room_name": "Superior Double",
"rate_id": "<string>",
"board_type": "BB",
"board_name": "Breakfast Included",
"max_occupancy": 123,
"taxes_and_fees": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"policies": [
{
"type": "<string>",
"description": "<string>",
"fee_amount": 123,
"fee_currency": "<string>",
"fee_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
}
}
],
"is_refundable": true,
"cancellation_policy": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"free_cancellation_until": "<string>",
"payment_types": [
"pay_now"
],
"remarks": "<string>"
}
]
}
]
}
],
"offers": [
{
"offer_id": "<string>",
"total_amount": 1818.4,
"currency": "EUR",
"is_refundable": true,
"taxes_breakdown": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"room_rates": [
{
"room_id": "<string>",
"occupancy_number": 2,
"occupancy": {
"adults": 2,
"children_ages": [
8
]
},
"taxes_and_fees": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"is_refundable": true,
"rate_id": "<string>",
"room_name": "<string>",
"board_type": "<string>",
"board_name": "<string>",
"max_occupancy": 123,
"policies": [
{
"type": "<string>",
"description": "<string>",
"fee_amount": 123,
"fee_currency": "<string>",
"fee_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
}
}
],
"cancellation_policy": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"free_cancellation_until": "<string>",
"payment_types": [
"pay_now"
],
"remarks": "<string>"
}
],
"board_type": "RO",
"board_name": "Room Only",
"total_amount_display": "EUR 606.13",
"total_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"free_cancellation_until": "2026-08-18T10:00:00+02:00",
"cancellation_schedule": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"payment_types": [
"pay_now"
],
"promotions": [
{
"code": "<string>",
"name": "<string>",
"remark": "<string>"
}
]
}
]
}
],
"nearby_alternatives": [
{
"hotel_id": "lp1d2c3",
"hotel_ref": "<string>",
"name": "Hôtel Le Marais",
"address": "12 Rue de Rivoli",
"city": "Paris",
"country": "fr",
"star_rating": 4,
"category": "4 KEYS",
"lodging_type": "Aparthotel",
"rating": 8.6,
"review_count": 1243,
"main_photo": "https://images.example.com/hotels/main.jpg",
"thumbnail": "https://images.example.com/hotels/thumb.jpg",
"latitude": 48.8566,
"longitude": 2.3522,
"distance_km": 1,
"recommendation_score": 0.5,
"intent_match_probability": 0.5,
"intent_confidence": 0.5,
"intent_evidence_status": "matched",
"intent_facts": {
"source": "hotel_catalog",
"name": "<string>",
"description": "<string>",
"facility_labels": [
"<string>"
],
"name_truncated": true,
"description_truncated": true,
"facility_labels_truncated": true,
"omitted_facts_status": "unknown"
},
"rooms": [
{
"room_id": "rm_1",
"room_name": "Superior Double",
"description": "<string>",
"requested_occupancy": 2,
"room_capacity": 2,
"max_occupancy": 2,
"images": [
"<string>"
],
"amenities": [
"<string>"
],
"beds": [
{
"bed_type": "<string>",
"count": 2
}
],
"rates": [
{
"offer_id": "htl_2d67a7441c60e5de",
"board_type": "RO",
"board_name": "Room Only",
"total_amount": 1818.4,
"total_amount_display": "EUR 606.13",
"currency": "EUR",
"total_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"is_refundable": false,
"free_cancellation_until": "2026-08-18T10:00:00+02:00",
"cancellation_schedule": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"taxes_breakdown": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"payment_types": [
"pay_now"
],
"promotions": [
{
"code": "<string>",
"name": "<string>",
"remark": "<string>"
}
],
"booking_scope": "room_bundle",
"num_rooms": 2,
"rooms": [
{
"occupancy_number": 1,
"occupancy": {
"adults": 2,
"children_ages": [
8
]
},
"room_id": "<string>",
"mapped_room_id": 123,
"room_name": "Superior Double",
"rate_id": "<string>",
"board_type": "BB",
"board_name": "Breakfast Included",
"max_occupancy": 123,
"taxes_and_fees": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"policies": [
{
"type": "<string>",
"description": "<string>",
"fee_amount": 123,
"fee_currency": "<string>",
"fee_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
}
}
],
"is_refundable": true,
"cancellation_policy": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"free_cancellation_until": "<string>",
"payment_types": [
"pay_now"
],
"remarks": "<string>"
}
]
}
]
}
],
"offers": [
{
"offer_id": "<string>",
"total_amount": 1818.4,
"currency": "EUR",
"is_refundable": true,
"taxes_breakdown": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"room_rates": [
{
"room_id": "<string>",
"occupancy_number": 2,
"occupancy": {
"adults": 2,
"children_ages": [
8
]
},
"taxes_and_fees": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"is_refundable": true,
"rate_id": "<string>",
"room_name": "<string>",
"board_type": "<string>",
"board_name": "<string>",
"max_occupancy": 123,
"policies": [
{
"type": "<string>",
"description": "<string>",
"fee_amount": 123,
"fee_currency": "<string>",
"fee_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
}
}
],
"cancellation_policy": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"free_cancellation_until": "<string>",
"payment_types": [
"pay_now"
],
"remarks": "<string>"
}
],
"board_type": "RO",
"board_name": "Room Only",
"total_amount_display": "EUR 606.13",
"total_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"free_cancellation_until": "2026-08-18T10:00:00+02:00",
"cancellation_schedule": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"payment_types": [
"pay_now"
],
"promotions": [
{
"code": "<string>",
"name": "<string>",
"remark": "<string>"
}
]
}
]
}
],
"total": 87,
"search_handle": "hs_example",
"next_handle": "hp_example_2",
"has_more": true,
"expires_at": "2027-01-15T10:30:00Z",
"search_scope": {
"plan_kind": "specific_hotels",
"coverage": "requested_hotels",
"coverage_unknown": true,
"snapshot_size": 1,
"candidate_count": 1,
"truncated": true,
"providers": [
{
"plan_kind": "specific_hotels",
"coverage": "requested_hotels",
"coverage_unknown": true,
"snapshot_size": 1,
"candidate_count": 1,
"truncated": true
}
]
},
"search_context": {
"checkin": "<string>",
"checkout": "<string>",
"occupancies": [
{
"adults": 2,
"children_ages": [
8
]
}
],
"currency": "<string>",
"guest_nationality": "<string>",
"trip_id": "<string>"
},
"warnings": [
"<string>"
],
"budget_filter": {
"max_budget_per_night": 150,
"currency": "EUR",
"max_budget_per_night_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"nights": 3,
"pages_fetched": 2,
"catalog_exhausted": true,
"hotels_dropped": 34
},
"internal_search": {},
"destination_resolution": {
"shape": "city",
"match": "exact",
"status": "resolved",
"requested_city": "Sain Malo",
"requested_country": "FR",
"resolved_city": "Saint Malo",
"resolved_country": "FR",
"latitude": 48.649,
"longitude": -2.0257,
"radius_km": 123,
"catalog_hotel_count": 41,
"score": 0.9,
"place_id": "<string>",
"query": "<string>",
"hotel_id": "lp1d2c3",
"hotel_name": "<string>",
"hotel_city": "<string>",
"nearby_alternatives_included": true,
"hotel_ids": [
"<string>"
],
"hotel_ids_without_rates": [
"<string>"
]
},
"empty_reason": "no_availability_for_dates"
}{
"error": {
"code": "BAD_REQUEST",
"message": "The request was declined for these inputs. Check the dates, places and travellers, then retry."
}
}{
"error": {
"code": "AUTH_REQUIRED",
"message": "Invalid or expired API key.",
"doc_url": "https://docs.gojinko.com/authentication/api-keys"
}
}{
"error": {
"code": "PAYMENT_REQUIRED",
"message": "Insufficient balance — this call costs $0.0150 and your organization has $0.0000 available. Top up at https://dashboard.gojinko.com/developers/billing/topup",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "CONFLICT",
"message": "The operation conflicts with the current state of the resource.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "GONE",
"message": "The resource no longer exists.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "DESTINATION_LOW_CONFIDENCE",
"message": "no confident city match for \"Sain Malo\" in FR (closest: \"Saint Malo\", FR at 0.75)",
"top_candidates": [
{
"city": "Saint Malo",
"country_code": "FR",
"hotel_count": 326,
"score": 0.75
}
],
"suggested_retry": {
"destination": {
"city_name": "Saint Malo",
"country_code": "FR"
},
"rationale": "the closest catalog city to the requested name; retry with it, or ask the user when the candidates differ"
}
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "Too many requests. Retry after the Retry-After delay.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "UPSTREAM_REJECTED",
"message": "The request was declined for this offer. Try another offer.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "UPSTREAM_UNAVAILABLE",
"message": "The service is temporarily unavailable. Retry after the Retry-After delay.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "UPSTREAM_TIMEOUT",
"message": "The request timed out before a result was available. Retry the request.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}Hotels
hotel-search
Search live hotel inventory and rates
POST
/
v1
/
hotel_search
Search live hotel inventory and rates
curl --request POST \
--url https://api.gojinko.com/v1/hotel_search \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"next_handle": "hp_example_2"
}
'import requests
url = "https://api.gojinko.com/v1/hotel_search"
payload = { "next_handle": "hp_example_2" }
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({next_handle: 'hp_example_2'})
};
fetch('https://api.gojinko.com/v1/hotel_search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.gojinko.com/v1/hotel_search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'next_handle' => 'hp_example_2'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.gojinko.com/v1/hotel_search"
payload := strings.NewReader("{\n \"next_handle\": \"hp_example_2\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.gojinko.com/v1/hotel_search")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"next_handle\": \"hp_example_2\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.gojinko.com/v1/hotel_search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"next_handle\": \"hp_example_2\"\n}"
response = http.request(request)
puts response.read_body{
"hotels": [
{
"hotel_id": "lp1d2c3",
"hotel_ref": "<string>",
"name": "Hôtel Le Marais",
"address": "12 Rue de Rivoli",
"city": "Paris",
"country": "fr",
"star_rating": 4,
"category": "4 KEYS",
"lodging_type": "Aparthotel",
"rating": 8.6,
"review_count": 1243,
"main_photo": "https://images.example.com/hotels/main.jpg",
"thumbnail": "https://images.example.com/hotels/thumb.jpg",
"latitude": 48.8566,
"longitude": 2.3522,
"distance_km": 1,
"recommendation_score": 0.5,
"intent_match_probability": 0.5,
"intent_confidence": 0.5,
"intent_evidence_status": "matched",
"intent_facts": {
"source": "hotel_catalog",
"name": "<string>",
"description": "<string>",
"facility_labels": [
"<string>"
],
"name_truncated": true,
"description_truncated": true,
"facility_labels_truncated": true,
"omitted_facts_status": "unknown"
},
"rooms": [
{
"room_id": "rm_1",
"room_name": "Superior Double",
"description": "<string>",
"requested_occupancy": 2,
"room_capacity": 2,
"max_occupancy": 2,
"images": [
"<string>"
],
"amenities": [
"<string>"
],
"beds": [
{
"bed_type": "<string>",
"count": 2
}
],
"rates": [
{
"offer_id": "htl_2d67a7441c60e5de",
"board_type": "RO",
"board_name": "Room Only",
"total_amount": 1818.4,
"total_amount_display": "EUR 606.13",
"currency": "EUR",
"total_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"is_refundable": false,
"free_cancellation_until": "2026-08-18T10:00:00+02:00",
"cancellation_schedule": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"taxes_breakdown": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"payment_types": [
"pay_now"
],
"promotions": [
{
"code": "<string>",
"name": "<string>",
"remark": "<string>"
}
],
"booking_scope": "room_bundle",
"num_rooms": 2,
"rooms": [
{
"occupancy_number": 1,
"occupancy": {
"adults": 2,
"children_ages": [
8
]
},
"room_id": "<string>",
"mapped_room_id": 123,
"room_name": "Superior Double",
"rate_id": "<string>",
"board_type": "BB",
"board_name": "Breakfast Included",
"max_occupancy": 123,
"taxes_and_fees": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"policies": [
{
"type": "<string>",
"description": "<string>",
"fee_amount": 123,
"fee_currency": "<string>",
"fee_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
}
}
],
"is_refundable": true,
"cancellation_policy": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"free_cancellation_until": "<string>",
"payment_types": [
"pay_now"
],
"remarks": "<string>"
}
]
}
]
}
],
"offers": [
{
"offer_id": "<string>",
"total_amount": 1818.4,
"currency": "EUR",
"is_refundable": true,
"taxes_breakdown": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"room_rates": [
{
"room_id": "<string>",
"occupancy_number": 2,
"occupancy": {
"adults": 2,
"children_ages": [
8
]
},
"taxes_and_fees": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"is_refundable": true,
"rate_id": "<string>",
"room_name": "<string>",
"board_type": "<string>",
"board_name": "<string>",
"max_occupancy": 123,
"policies": [
{
"type": "<string>",
"description": "<string>",
"fee_amount": 123,
"fee_currency": "<string>",
"fee_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
}
}
],
"cancellation_policy": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"free_cancellation_until": "<string>",
"payment_types": [
"pay_now"
],
"remarks": "<string>"
}
],
"board_type": "RO",
"board_name": "Room Only",
"total_amount_display": "EUR 606.13",
"total_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"free_cancellation_until": "2026-08-18T10:00:00+02:00",
"cancellation_schedule": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"payment_types": [
"pay_now"
],
"promotions": [
{
"code": "<string>",
"name": "<string>",
"remark": "<string>"
}
]
}
]
}
],
"nearby_alternatives": [
{
"hotel_id": "lp1d2c3",
"hotel_ref": "<string>",
"name": "Hôtel Le Marais",
"address": "12 Rue de Rivoli",
"city": "Paris",
"country": "fr",
"star_rating": 4,
"category": "4 KEYS",
"lodging_type": "Aparthotel",
"rating": 8.6,
"review_count": 1243,
"main_photo": "https://images.example.com/hotels/main.jpg",
"thumbnail": "https://images.example.com/hotels/thumb.jpg",
"latitude": 48.8566,
"longitude": 2.3522,
"distance_km": 1,
"recommendation_score": 0.5,
"intent_match_probability": 0.5,
"intent_confidence": 0.5,
"intent_evidence_status": "matched",
"intent_facts": {
"source": "hotel_catalog",
"name": "<string>",
"description": "<string>",
"facility_labels": [
"<string>"
],
"name_truncated": true,
"description_truncated": true,
"facility_labels_truncated": true,
"omitted_facts_status": "unknown"
},
"rooms": [
{
"room_id": "rm_1",
"room_name": "Superior Double",
"description": "<string>",
"requested_occupancy": 2,
"room_capacity": 2,
"max_occupancy": 2,
"images": [
"<string>"
],
"amenities": [
"<string>"
],
"beds": [
{
"bed_type": "<string>",
"count": 2
}
],
"rates": [
{
"offer_id": "htl_2d67a7441c60e5de",
"board_type": "RO",
"board_name": "Room Only",
"total_amount": 1818.4,
"total_amount_display": "EUR 606.13",
"currency": "EUR",
"total_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"is_refundable": false,
"free_cancellation_until": "2026-08-18T10:00:00+02:00",
"cancellation_schedule": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"taxes_breakdown": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"payment_types": [
"pay_now"
],
"promotions": [
{
"code": "<string>",
"name": "<string>",
"remark": "<string>"
}
],
"booking_scope": "room_bundle",
"num_rooms": 2,
"rooms": [
{
"occupancy_number": 1,
"occupancy": {
"adults": 2,
"children_ages": [
8
]
},
"room_id": "<string>",
"mapped_room_id": 123,
"room_name": "Superior Double",
"rate_id": "<string>",
"board_type": "BB",
"board_name": "Breakfast Included",
"max_occupancy": 123,
"taxes_and_fees": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"policies": [
{
"type": "<string>",
"description": "<string>",
"fee_amount": 123,
"fee_currency": "<string>",
"fee_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
}
}
],
"is_refundable": true,
"cancellation_policy": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"free_cancellation_until": "<string>",
"payment_types": [
"pay_now"
],
"remarks": "<string>"
}
]
}
]
}
],
"offers": [
{
"offer_id": "<string>",
"total_amount": 1818.4,
"currency": "EUR",
"is_refundable": true,
"taxes_breakdown": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"room_rates": [
{
"room_id": "<string>",
"occupancy_number": 2,
"occupancy": {
"adults": 2,
"children_ages": [
8
]
},
"taxes_and_fees": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"is_refundable": true,
"rate_id": "<string>",
"room_name": "<string>",
"board_type": "<string>",
"board_name": "<string>",
"max_occupancy": 123,
"policies": [
{
"type": "<string>",
"description": "<string>",
"fee_amount": 123,
"fee_currency": "<string>",
"fee_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
}
}
],
"cancellation_policy": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"free_cancellation_until": "<string>",
"payment_types": [
"pay_now"
],
"remarks": "<string>"
}
],
"board_type": "RO",
"board_name": "Room Only",
"total_amount_display": "EUR 606.13",
"total_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"free_cancellation_until": "2026-08-18T10:00:00+02:00",
"cancellation_schedule": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"payment_types": [
"pay_now"
],
"promotions": [
{
"code": "<string>",
"name": "<string>",
"remark": "<string>"
}
]
}
]
}
],
"total": 87,
"search_handle": "hs_example",
"next_handle": "hp_example_2",
"has_more": true,
"expires_at": "2027-01-15T10:30:00Z",
"search_scope": {
"plan_kind": "specific_hotels",
"coverage": "requested_hotels",
"coverage_unknown": true,
"snapshot_size": 1,
"candidate_count": 1,
"truncated": true,
"providers": [
{
"plan_kind": "specific_hotels",
"coverage": "requested_hotels",
"coverage_unknown": true,
"snapshot_size": 1,
"candidate_count": 1,
"truncated": true
}
]
},
"search_context": {
"checkin": "<string>",
"checkout": "<string>",
"occupancies": [
{
"adults": 2,
"children_ages": [
8
]
}
],
"currency": "<string>",
"guest_nationality": "<string>",
"trip_id": "<string>"
},
"warnings": [
"<string>"
],
"budget_filter": {
"max_budget_per_night": 150,
"currency": "EUR",
"max_budget_per_night_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"nights": 3,
"pages_fetched": 2,
"catalog_exhausted": true,
"hotels_dropped": 34
},
"internal_search": {},
"destination_resolution": {
"shape": "city",
"match": "exact",
"status": "resolved",
"requested_city": "Sain Malo",
"requested_country": "FR",
"resolved_city": "Saint Malo",
"resolved_country": "FR",
"latitude": 48.649,
"longitude": -2.0257,
"radius_km": 123,
"catalog_hotel_count": 41,
"score": 0.9,
"place_id": "<string>",
"query": "<string>",
"hotel_id": "lp1d2c3",
"hotel_name": "<string>",
"hotel_city": "<string>",
"nearby_alternatives_included": true,
"hotel_ids": [
"<string>"
],
"hotel_ids_without_rates": [
"<string>"
]
},
"empty_reason": "no_availability_for_dates"
}{
"error": {
"code": "BAD_REQUEST",
"message": "The request was declined for these inputs. Check the dates, places and travellers, then retry."
}
}{
"error": {
"code": "AUTH_REQUIRED",
"message": "Invalid or expired API key.",
"doc_url": "https://docs.gojinko.com/authentication/api-keys"
}
}{
"error": {
"code": "PAYMENT_REQUIRED",
"message": "Insufficient balance — this call costs $0.0150 and your organization has $0.0000 available. Top up at https://dashboard.gojinko.com/developers/billing/topup",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "CONFLICT",
"message": "The operation conflicts with the current state of the resource.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "GONE",
"message": "The resource no longer exists.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "DESTINATION_LOW_CONFIDENCE",
"message": "no confident city match for \"Sain Malo\" in FR (closest: \"Saint Malo\", FR at 0.75)",
"top_candidates": [
{
"city": "Saint Malo",
"country_code": "FR",
"hotel_count": 326,
"score": 0.75
}
],
"suggested_retry": {
"destination": {
"city_name": "Saint Malo",
"country_code": "FR"
},
"rationale": "the closest catalog city to the requested name; retry with it, or ask the user when the candidates differ"
}
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "Too many requests. Retry after the Retry-After delay.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "UPSTREAM_REJECTED",
"message": "The request was declined for this offer. Try another offer.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "UPSTREAM_UNAVAILABLE",
"message": "The service is temporarily unavailable. Retry after the Retry-After delay.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "UPSTREAM_TIMEOUT",
"message": "The request timed out before a result was available. Retry the request.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}Search live hotel inventory and nightly rates for a destination and stay window. It handles requests like “three nights in Lisbon next weekend for two adults” or “family room in Rome with one child in August”. Each result includes an
htl_* offer token you can hand to the trip tool to start a booking.
Read hotel prices from the
*_money fields. rates[].total_amount_money,
taxes_breakdown[].amount_money and cancellation_schedule[].amount_money
carry value in minor units with its decimal_places, the same shape as
every other money field: divide value by 10 ** decimal_places, or show
display. A cancellation step expressed as a percentage or a number of
nights carries percent or nights instead. The older total_amount,
amount and currency fields are deprecated and hold major units. A room’s
capacity is room_capacity; the deprecated max_occupancy repeats the
requested occupancy. See Money & prices.Authorizations
ApiKeyAuthBearerAuth
Body
application/json
- Option 1
- Option 2
Opaque continuation handle returned by a prior hotel_search. Send this field by itself; the search session keeps destination, dates, occupancy, currency and filters.
Minimum string length:
1Example:
"hp_example_2"
Response
Matching hotels
Show child attributes
Show child attributes
Other hotels near the one a hotel_name search matched, priced for the same dates and occupancy, so they can be compared without a second search. Same shape as hotels, and not counted in total. Present only on a hotel_name search that found usable neighbours.
Show child attributes
Show child attributes
Example:
87
Stable opaque identifier for the fixed search session.
Example:
"hs_example"
Opaque handle for the next deterministic page. Send it by itself to hotel_search. Null means the fixed search scope is exhausted.
Example:
"hp_example_2"
Whether this fixed search session has another page.
RFC 3339 expiry for the search session and its page handles.
Example:
"2027-01-15T10:30:00Z"
Finite result scope frozen by this search session. Optional counts describe the fixed snapshot or ranked candidate pool.
Show child attributes
Show child attributes
Normalized first-request stay and occupancy frozen by the search session and repeated on every page. trip_id is display/cart association only.
Show child attributes
Show child attributes
Non-fatal advisories, e.g. budget-filter outcomes or ignored filters.
How the max_budget_per_night filter shaped the response (present only when set).
Show child attributes
Show child attributes
Search metadata for diagnostics. Its fields can change without notice; do not build on them.
How the request’s destination resolved into these hotels. Present on every successful search. Rendering rule for an agent or tool: say something ONLY when there is something to say — match is fuzzy or fallback_string, or resolved_city differs from requested_city. exact and provider_matched need no header line of their own.
Show child attributes
Show child attributes
Why hotels is empty. Absent whenever hotels is non-empty.
Available options:
no_availability_for_dates, destination_not_found, catalog_exhausted, all_dropped_by_budget, no_catalog_match, all_dropped_by_star_filter Example:
"no_availability_for_dates"