--- title: "Search live car rental offers" method: POST path: "/v1/car_search" tags: ["Cars"] --- # Search live car rental offers `POST /v1/car_search` ## Request - Base URL: `https://api.gojinko.com` - URL: `https://api.gojinko.com/v1/car_search` - Auth: one of: - API key in header `X-API-Key` - HTTP bearer Search live car rental availability. `pick_up` names exactly one of an `airport_code` (IATA), a free-text `place` (resolved server-side — ambiguous text returns `candidates` to retry with), or `geo` coordinates (round-trip only). Date-times are branch-local `YYYY-MM-DDTHH:MM:SS` with no timezone. Omit `drop_off` to return the car to the pick-up branch, setting `drop_off_date_time`. Pass each offer's `trip_item_token` verbatim to `POST /v1/trip` as `add_item.trip_item_token` to add the rental to a trip, then check out as normal. `price.pay_now` is the only amount Jinko charges — `due_at_desk` is collected by the rental desk locally. ## Request body - CarSearchRequest: `pick_up` names exactly one of `airport_code`, `place` or `geo`, and a drop-off time must come from `drop_off.date_time` or `drop_off_date_time`. These rules are enforced at runtime but cannot be expressed in JSON Schema, so they do not appear in `required`. - `pick_up` CarPickUp, required - `date_time` string, required: Pick-up date-time, branch-local, no timezone. - `airport_code` string: IATA airport code. - `place` string: Free-text location — a city, district or landmark. Resolved server-side; when the text is ambiguous the response carries `candidates` instead of offers — retry with a candidate's `name`. - `geo` CarGeo: Coordinates + radius. Searches the closest rental branches. Geo search is round-trip only: `drop_off` must be omitted or name the same place. - `latitude` number, required - `longitude` number, required - `range` integer, required: Search radius around the coordinates, in metres (minimum 50). - `drop_off` CarDropOff: Where the car is returned. Omit for a round trip (return to the pick-up branch) and set `drop_off_date_time` instead. - `date_time` string: Drop-off date-time, branch-local. May instead be given as the top-level `drop_off_date_time`. - `airport_code` string: IATA airport code. - `place` string: Free-text location — a city, district or landmark. Resolved server-side; when the text is ambiguous the response carries `candidates` instead of offers — retry with a candidate's `name`. - `geo` CarGeo: Coordinates + radius. Searches the closest rental branches. Geo search is round-trip only: `drop_off` must be omitted or name the same place. - `latitude` number, required - `longitude` number, required - `range` integer, required: Search radius around the coordinates, in metres (minimum 50). - `drop_off_date_time` string: Drop-off date-time for a round trip, branch-local. Required when `drop_off` is omitted. - `driver_age` integer, required: Driver's age at pick-up (18-99). Pricing and availability are age-dependent. - `residence_country` string, required: Driver's country of residence, ISO 3166-1 alpha-2. Rates and inclusions vary by residence. - `currency` string: ISO 4217 display currency. Defaults to USD. - `lang` string: BCP-47 language tag for vehicle and branch text. - `intent` IntentInput - `user_intent` string, nullable: The user's natural-language intent: the Alpic PII-stripped paraphrase when available, else a best-effort fallback to the client-provided NL query. ## Response `200` Bookable car rental offers - CarSearchResponse - `offers` CarOffer[] - `trip_item_token` string, required: The trip item token. Pass verbatim to POST /v1/trip as `add_item.trip_item_token` to add this rental to a trip. - `offer_id` string, required: Deprecated: use `trip_item_token` instead. Same value. - `vehicle` CarVehicle - `acriss_code` string - `name` string - `category` string - `type` string - `transmission` string - `fuel_type` string - `seats` string: A string — suppliers publish ranges like "5-7". - `doors` string: A string, like seats. - `big_suitcases` integer - `small_suitcases` integer - `air_conditioned` boolean - `built_in_gps` boolean - `model_guaranteed` boolean: False is the ordinary "or similar" rental promise: the supplier guarantees the class, not this exact model. Do not present the model as confirmed unless this is true. - `supplier_code` string: The supplier's own code for this vehicle class, not for the rental company — cars from one company carry many different values here. Opaque; do not parse or match companies on it. - `images` CarImage[] - `url` string - `package` CarPackage - `name` string - `code` string: The provider's own code for this rate package. Opaque. - `supplier_name` string: The rental company the driver actually collects the car from — Avis, Hertz, Europcar, Sixt. It is that company, not Jinko or any intermediary, whose desk, deposit rules and fuel policy apply, so it is the supplier identity to show a customer. Read off the pick-up branch, so a one-way rental names the collecting company, never the returning one. - `supplier_code` string: The pick-up branch's own code, scoped to a station rather than to a company. Opaque, and NOT comparable with vehicle.supplier_code — match companies on supplier_name. - `fuel_policy` string - `mileage_unlimited` boolean - `mileage_allowance` string - `inclusions` unknown[] - unknown - `coverages` CarCoverage[] - `name` string - `excess` CarAmount - `value` integer: Integer amount in MINOR units, always paired with decimal_places — divide by 10 ** decimal_places to display. Example: value 15977 with decimal_places 2 is 159.77 USD. Rendering this field directly shows prices 100x too high for 2-decimal currencies. - `currency` string: ISO 4217 currency code. - `decimal_places` integer: Scale of the integer value/amount: display = integer / 10 ** decimal_places. Always sent alongside minor-unit amounts. Usually the ISO 4217 digits of the currency (2 for USD/EUR/GBP, 0 for JPY/KRW, 3 for BHD/JOD/KWD) but currency-converted prices can carry a different scale — ALWAYS use the decimal_places sent with the amount, never a hardcoded 2. Only if the field is genuinely absent on a value-shaped object, fall back to the ISO digits for the currency. - `display` string: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount, e.g. "USD 159.77". With decimal_places it is written at exactly that scale (value 1561500, JPY, decimal_places 2 is "JPY 15615.00"); without, at the ISO digits of the currency. Show this; compute with the number. Absent when the figure is not money (a cancellation step expressed as a percent or a number of nights) or could not be read unambiguously. - `included_in_vehicle_price` boolean - `mandatory` boolean - `paid_at` string - `price` CarAmount - `value` integer: Integer amount in MINOR units, always paired with decimal_places — divide by 10 ** decimal_places to display. Example: value 15977 with decimal_places 2 is 159.77 USD. Rendering this field directly shows prices 100x too high for 2-decimal currencies. - `currency` string: ISO 4217 currency code. - `decimal_places` integer: Scale of the integer value/amount: display = integer / 10 ** decimal_places. Always sent alongside minor-unit amounts. Usually the ISO 4217 digits of the currency (2 for USD/EUR/GBP, 0 for JPY/KRW, 3 for BHD/JOD/KWD) but currency-converted prices can carry a different scale — ALWAYS use the decimal_places sent with the amount, never a hardcoded 2. Only if the field is genuinely absent on a value-shaped object, fall back to the ISO digits for the currency. - `display` string: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount, e.g. "USD 159.77". With decimal_places it is written at exactly that scale (value 1561500, JPY, decimal_places 2 is "JPY 15615.00"); without, at the ISO digits of the currency. Show this; compute with the number. Absent when the figure is not money (a cancellation step expressed as a percent or a number of nights) or could not be read unambiguously. - `fees` CarFee[] - `name` string - `included_in_vehicle_price` boolean - `mandatory` boolean - `paid_at` string - `price` CarAmount - `value` integer: Integer amount in MINOR units, always paired with decimal_places — divide by 10 ** decimal_places to display. Example: value 15977 with decimal_places 2 is 159.77 USD. Rendering this field directly shows prices 100x too high for 2-decimal currencies. - `currency` string: ISO 4217 currency code. - `decimal_places` integer: Scale of the integer value/amount: display = integer / 10 ** decimal_places. Always sent alongside minor-unit amounts. Usually the ISO 4217 digits of the currency (2 for USD/EUR/GBP, 0 for JPY/KRW, 3 for BHD/JOD/KWD) but currency-converted prices can carry a different scale — ALWAYS use the decimal_places sent with the amount, never a hardcoded 2. Only if the field is genuinely absent on a value-shaped object, fall back to the ISO digits for the currency. - `display` string: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount, e.g. "USD 159.77". With decimal_places it is written at exactly that scale (value 1561500, JPY, decimal_places 2 is "JPY 15615.00"); without, at the ISO digits of the currency. Show this; compute with the number. Absent when the figure is not money (a cancellation step expressed as a percent or a number of nights) or could not be read unambiguously. - `pick_up` CarBranch - `name` string - `address` string - `city` string - `country` string - `phone` string - `date_time` string: The pick-up or drop-off time at this branch, branch-local. - `time_zone` string - `latitude` number - `longitude` number - `opening_hours` string: The branch's published hours, as supplied. Free text, not a parseable schedule. - `out_of_hours` boolean: This pick-up or drop-off falls outside the published hours, which usually carries a surcharge. Only asserted when that day's hours were published, so false means "within hours, or not stated" and never "checked and fine". - `requires_flight_number` string: The branch policy: "never", "always" or "out_of_hours_pickup". Jinko carries no flight number today, so "always" means this branch cannot be booked — prefer an offer from another branch. - `terminals` string[]: The airport terminals this branch serves, when it is at one. - `is_meet_and_greet` boolean: The supplier meets the driver instead of staffing a desk, so there is nowhere to walk up to. Tell the customer to expect a meeting point. - `drop_off` CarBranch - `name` string - `address` string - `city` string - `country` string - `phone` string - `date_time` string: The pick-up or drop-off time at this branch, branch-local. - `time_zone` string - `latitude` number - `longitude` number - `opening_hours` string: The branch's published hours, as supplied. Free text, not a parseable schedule. - `out_of_hours` boolean: This pick-up or drop-off falls outside the published hours, which usually carries a surcharge. Only asserted when that day's hours were published, so false means "within hours, or not stated" and never "checked and fine". - `requires_flight_number` string: The branch policy: "never", "always" or "out_of_hours_pickup". Jinko carries no flight number today, so "always" means this branch cannot be booked — prefer an offer from another branch. - `terminals` string[]: The airport terminals this branch serves, when it is at one. - `is_meet_and_greet` boolean: The supplier meets the driver instead of staffing a desk, so there is nowhere to walk up to. Tell the customer to expect a meeting point. - `price` CarOfferPrice - `pay_now` object: The only amount Jinko charges at checkout. - `value` integer: Integer amount in MINOR units, always paired with decimal_places — divide by 10 ** decimal_places to display. Example: value 15977 with decimal_places 2 is 159.77 USD. Rendering this field directly shows prices 100x too high for 2-decimal currencies. - `currency` string: ISO 4217 currency code. - `decimal_places` integer: Scale of the integer value/amount: display = integer / 10 ** decimal_places. Always sent alongside minor-unit amounts. Usually the ISO 4217 digits of the currency (2 for USD/EUR/GBP, 0 for JPY/KRW, 3 for BHD/JOD/KWD) but currency-converted prices can carry a different scale — ALWAYS use the decimal_places sent with the amount, never a hardcoded 2. Only if the field is genuinely absent on a value-shaped object, fall back to the ISO digits for the currency. - `display` string: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount, e.g. "USD 159.77". With decimal_places it is written at exactly that scale (value 1561500, JPY, decimal_places 2 is "JPY 15615.00"); without, at the ISO digits of the currency. Show this; compute with the number. Absent when the figure is not money (a cancellation step expressed as a percent or a number of nights) or could not be read unambiguously. - `due_at_desk` object: Collected by the rental desk locally, in local currency. Display-only. - `value` integer: Integer amount in MINOR units, always paired with decimal_places — divide by 10 ** decimal_places to display. Example: value 15977 with decimal_places 2 is 159.77 USD. Rendering this field directly shows prices 100x too high for 2-decimal currencies. - `currency` string: ISO 4217 currency code. - `decimal_places` integer: Scale of the integer value/amount: display = integer / 10 ** decimal_places. Always sent alongside minor-unit amounts. Usually the ISO 4217 digits of the currency (2 for USD/EUR/GBP, 0 for JPY/KRW, 3 for BHD/JOD/KWD) but currency-converted prices can carry a different scale — ALWAYS use the decimal_places sent with the amount, never a hardcoded 2. Only if the field is genuinely absent on a value-shaped object, fall back to the ISO digits for the currency. - `display` string: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount, e.g. "USD 159.77". With decimal_places it is written at exactly that scale (value 1561500, JPY, decimal_places 2 is "JPY 15615.00"); without, at the ISO digits of the currency. Show this; compute with the number. Absent when the figure is not money (a cancellation step expressed as a percent or a number of nights) or could not be read unambiguously. - `estimated_total` object: pay_now + due_at_desk, where both are known. - `value` integer: Integer amount in MINOR units, always paired with decimal_places — divide by 10 ** decimal_places to display. Example: value 15977 with decimal_places 2 is 159.77 USD. Rendering this field directly shows prices 100x too high for 2-decimal currencies. - `currency` string: ISO 4217 currency code. - `decimal_places` integer: Scale of the integer value/amount: display = integer / 10 ** decimal_places. Always sent alongside minor-unit amounts. Usually the ISO 4217 digits of the currency (2 for USD/EUR/GBP, 0 for JPY/KRW, 3 for BHD/JOD/KWD) but currency-converted prices can carry a different scale — ALWAYS use the decimal_places sent with the amount, never a hardcoded 2. Only if the field is genuinely absent on a value-shaped object, fall back to the ISO digits for the currency. - `display` string: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount, e.g. "USD 159.77". With decimal_places it is written at exactly that scale (value 1561500, JPY, decimal_places 2 is "JPY 15615.00"); without, at the ISO digits of the currency. Show this; compute with the number. Absent when the figure is not money (a cancellation step expressed as a percent or a number of nights) or could not be read unambiguously. - `deposit` object: Security hold taken at the desk, not a charge. - `value` integer: Integer amount in MINOR units, always paired with decimal_places — divide by 10 ** decimal_places to display. Example: value 15977 with decimal_places 2 is 159.77 USD. Rendering this field directly shows prices 100x too high for 2-decimal currencies. - `currency` string: ISO 4217 currency code. - `decimal_places` integer: Scale of the integer value/amount: display = integer / 10 ** decimal_places. Always sent alongside minor-unit amounts. Usually the ISO 4217 digits of the currency (2 for USD/EUR/GBP, 0 for JPY/KRW, 3 for BHD/JOD/KWD) but currency-converted prices can carry a different scale — ALWAYS use the decimal_places sent with the amount, never a hardcoded 2. Only if the field is genuinely absent on a value-shaped object, fall back to the ISO digits for the currency. - `display` string: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount, e.g. "USD 159.77". With decimal_places it is written at exactly that scale (value 1561500, JPY, decimal_places 2 is "JPY 15615.00"); without, at the ISO digits of the currency. Show this; compute with the number. Absent when the figure is not money (a cancellation step expressed as a percent or a number of nights) or could not be read unambiguously. - `driver_age_range` CarDriverAgeRange: The age band this price was quoted for, as the supplier states it. A driver outside the band is refused at the counter. - `min` integer - `max` integer - `on_request` boolean: The supplier confirms availability after booking rather than instantly. - `cancellation_fees` CarCancellationFee[]: Fee tiers by time before pick-up. An EMPTY list means the schedule is unknown — never render it as free cancellation. - `type` string - `fee` CarAmount - `value` integer: Integer amount in MINOR units, always paired with decimal_places — divide by 10 ** decimal_places to display. Example: value 15977 with decimal_places 2 is 159.77 USD. Rendering this field directly shows prices 100x too high for 2-decimal currencies. - `currency` string: ISO 4217 currency code. - `decimal_places` integer: Scale of the integer value/amount: display = integer / 10 ** decimal_places. Always sent alongside minor-unit amounts. Usually the ISO 4217 digits of the currency (2 for USD/EUR/GBP, 0 for JPY/KRW, 3 for BHD/JOD/KWD) but currency-converted prices can carry a different scale — ALWAYS use the decimal_places sent with the amount, never a hardcoded 2. Only if the field is genuinely absent on a value-shaped object, fall back to the ISO digits for the currency. - `display` string: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount, e.g. "USD 159.77". With decimal_places it is written at exactly that scale (value 1561500, JPY, decimal_places 2 is "JPY 15615.00"); without, at the ISO digits of the currency. Show this; compute with the number. Absent when the figure is not money (a cancellation step expressed as a percent or a number of nights) or could not be read unambiguously. - `non_refundable` boolean - `applicable_from` string - `applicable_to` string - `applicable_now` boolean - `seconds_before_pick_up` number - `expires_at` string: When the trip_item_token stops being addable to a trip. Re-search after this. - `currency` string - `resolved_place` CarResolvedPlace: How a free-text `place` was interpreted. Echoed so the caller can confirm the resolution. - `name` string - `kind` string: One of "airport", "railway", "port" or "bus" — absent for a city-centre rental office. - `city` string - `country` string - `candidates` CarResolvedPlace[]: Returned instead of offers when a free-text `place` is ambiguous. Retry with `place` set to a candidate's `name`; when two candidates share a name, qualify it with the city — `"City Centre, Lyon"`. - `name` string - `kind` string: One of "airport", "railway", "port" or "bus" — absent for a city-centre rental office. - `city` string - `country` string - `warnings` object[] - `code` string - `message` string ## Other responses - `400`: Bad request - `401`: Authentication required - `402`: Payment required — organization balance exhausted - `404`: Resource not found - `409`: The operation conflicts with the current state of the resource - `410`: The resource this request names no longer exists - `422`: The request failed validation, or the rental supplier declined the search. When a supplier declined the request, `error.message` is “The rental request was declined. Try another vehicle, location or time.” **`BAD_REQUEST`** — The request was malformed or failed validation. Fix the request as the message describes; retrying it unchanged cannot succeed. - `429`: Rate limit or quota exceeded - `502`: The travel provider rejected the request, or an upstream call failed - `503`: No travel provider can serve the request right now - `504`: The travel provider did not answer in time --- [API](https://skmtc.dev/gojinko/apis/jinko-public-api.md) - [All operations](https://skmtc.dev/gojinko/apis/jinko-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gojinko/apis/jinko-public-api/revisions/ac5046767e4c?raw)