RankByCountry
const url = 'https://example.com/wink.partner.v1.Search/RankByCountry';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"userSession":{"itinerary":{"startDate":"example","nights":1,"room":{"adults":1,"children":[{"age":1,"quantity":1}],"quantity":1}},"languageCode":"example","currencyCode":"example","promotionalCodes":["example"]},"countryCode":"example","sort":"SCORE_SORT_UNSPECIFIED","searchFilters":{"nameSoundsLike":"example","lifestyle":"LIFESTYLE_TYPE_UNSPECIFIED","starRating":1,"directOnly":true},"page":1,"size":1,"imageFormat":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/wink.partner.v1.Search/RankByCountry \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "userSession": { "itinerary": { "startDate": "example", "nights": 1, "room": { "adults": 1, "children": [ { "age": 1, "quantity": 1 } ], "quantity": 1 } }, "languageCode": "example", "currencyCode": "example", "promotionalCodes": [ "example" ] }, "countryCode": "example", "sort": "SCORE_SORT_UNSPECIFIED", "searchFilters": { "nameSoundsLike": "example", "lifestyle": "LIFESTYLE_TYPE_UNSPECIFIED", "starRating": 1, "directOnly": true }, "page": 1, "size": 1, "imageFormat": "example" }'Rank a country’s properties
Return properties within a country, ordered by the scoring type you choose.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”Request for RankByCountry.
object
Traveller context. Required.
object
Stay dates and occupancy. Required — searches without an itinerary cannot be priced.
object
Check-in date, ISO-8601 “YYYY-MM-DD”. Required. Must be today or later – a past date is rejected with INVALID_ARGUMENT.
Number of nights. Billing caps this at 90; a longer stay is rejected with INVALID_ARGUMENT.
The room being searched for, and how many of it. Required.
SINGULAR. This was once a list, on the promise that several occupancies could be priced in one call —
two adults in one room and a family of four in another. The platform never delivered it: every
consumer read the FIRST entry and the room count came from the list’s SIZE, so a second entry was
priced as though it did not exist while still moving the count that volume discounts and availability
key off. Ask for several identical rooms with RoomConfiguration.quantity; ask for several DIFFERENT
occupancies as separate calls, and assemble them in your own cart.
object
Adults in this room. Defaults to 1.
Children in this room, by age. Ages are REQUIRED, not optional detail: properties price children in age bands, and an unpriceable age produces a rate the guest cannot actually book.
A number of children of the same age.
object
Age at check-in, in years. Zero is valid — infants are priced differently from older children, not ignored.
How many children of this age. Defaults to 1.
How many identical rooms of this configuration. Defaults to 1.
ISO 639-1 language, e.g. “en”. Affects the little text this surface returns; for descriptions and other prose, pass the language to the Content service instead. Defaults to “en”.
ISO 4217 currency for all returned prices, e.g. “THB”. Exactly three characters. Defaults to the property’s own currency.
Promotional codes to apply. Codes your account is not entitled to are ignored, not rejected.
ISO 3166-1 alpha-2 country code, e.g. “TH”. Required.
How to order the results.
Optional narrowing of the result set.
object
Fuzzy match on property name.
Restrict to properties oriented toward this lifestyle.
Minimum star rating, 1-5.
Only properties bookable direct, excluding intermediated inventory.
Zero-based page number. Defaults to 0.
Results per page. Defaults to 20, which is also the maximum. A larger value is rejected with INVALID_ARGUMENT rather than clamped, so a caller never pages through a result set believing it is larger than it is. Every property returned is billed, so the cap bounds cost as well as fan-out.
IANA media type for image delivery URLs: image/jpeg (the default), image/png, image/webp, or image/* to let the CDN negotiate per client from its Accept header. Empty means image/jpeg.
An unrecognised value is rejected with INVALID_ARGUMENT rather than quietly falling back, so a typo
like “image/jpg” (not a media type) fails loudly instead of serving you JPEG while you believe you
asked for something else. Whatever is served is echoed back on MediaUrlVariant.format.
Responses
Section titled “Responses”The RPC completed with gRPC status OK.
Response for RankByCountry.
object
One page of priced properties.
Wire mirror of the REST PageResponse envelope: number is zero-based and total_elements counts across
all pages, not this one.
object
The properties on this page.
One property and its live prices.
Carries only what a result list needs to render, plus the prices. For anything else about the property —
descriptions, full gallery, address, amenities, room detail, policies — call the Content service with
property_id and cache the answer against last_update.
object
Stable property identifier. Your key for everything, including Content lookups.
Url-safe slug, stable and safe to build links from.
The property’s globally unique short code.
Property name in the requested language. Enough to label a result row; full localized content comes from the Content service.
Where the property is, for map pins and distance sorting.
Bare latitude and longitude, not GeoJSON: this field carries only coordinates, and the surrounding
JSON already tells you what kind of thing they belong to. Named geo_location rather than location
so a generated client’s field name says what it is without opening the type.
object
Degrees east of the prime meridian, -180 to 180.
Degrees north of the equator, -90 to 90.
The city this property is in, with the identifiers the destination surfaces take.
Lets a result row offer “more properties in this city” without a Content call first: geo_name_id
goes straight back into SearchByCity, url_name into RankByCity. Absent when the property has no
city on record.
object
GeoNames id, e.g. “1609350” for Bangkok. Pass to Search.SearchByCity.
Always set when this message is present: every property that has a city has this.
The city’s name.
NOT localized, unlike every other name on this surface. The lightweight GeoNames record this comes
from deliberately excludes alternate-name translations, so this is the canonical GeoNames name
whatever language_code you asked for. Said plainly because a caller would otherwise reasonably
assume it follows the rest of the response.
Url-safe slug. Pass to Search.RankByCity, which takes the url name rather than the GeoNames id.
EMPTY for a substantial minority of properties – 601 of 3,230 in production, about 19% – because the slug is populated separately from the GeoNames link. Check it before building a RankByCity call; an empty value here does not mean the property has no city, only that this particular handle is missing.
ISO 3166-1 alpha-2 country code of the city, e.g. “TH”.
How far this property is from the point you searched from, in metres.
Set only when area held a point — a polygon has no single origin to measure from, so this is
unset on containment searches. On a point search the page is ordered by this value, nearest first.
It is the distance to the property’s nearest bookable inventory item, which is the property’s own location for all current inventory types.
optional so a genuine near-zero distance (the property is essentially at the search coordinates)
is distinguishable from “not applicable”: a plain, non-optional double serializes identically to
its own default at exactly 0, so proto3 JSON would otherwise omit both cases the same way.
Official star rating, 1-5. Zero when unrated.
A ready-to-use delivery URL for a single representative image of the property, scaled to 1024px wide
(Cloudinary’s medium variant), the same convention SearchRoomTypeOffers.hero_image_url already uses
for a room. The lowest-sorted published image; unset when the property has none.
A plain URL rather than the full Multimedia object deliberately: this is a pricing surface, not a content surface, and the full object carries localized captions, camera angle and lifestyle tagging – real content, not routing information for one image. The complete gallery is in Content.
When this property’s record last changed, ISO-8601 “YYYY-MM-DDThh:mm:ss” in UTC.
Use it as the cache key for your Content responses: store it alongside what you fetched, compare on each search, and re-fetch only when it has moved. It advances when the property or any inventory item beneath it is added, removed or edited.
Edits to child entities advance it too — room types, rate plans, master rates, cancellation policies and every ancillary item, on create, edit, remove and translate alike.
One documented gap: PERKS. A perk is defined once for the whole platform rather than per property, so editing one cannot be attributed to a single property and does not move any property’s value. Perk text you have cached can therefore go stale silently. Perks are small and few — the pricing surfaces return every perk referenced by a result inline — so read them from a search or inventory response rather than caching them against this value, and re-sync content periodically regardless.
Offers for this property, grouped by room type, cheapest room first. Search returns the single best offer per room type; use Inventory for every rate and occupancy combination.
object
The room type. Join to Content for the full gallery, amenities and long-form descriptions.
The room type’s name, in the requested language where a translation exists.
A ready-to-use delivery URL for a single representative image of the room, scaled to 1024px wide (Cloudinary’s medium variant — c_scale, dpr_auto, f_auto, q_auto:best, w_1024). The lowest-sorted published image; unset when the room has none.
A plain URL rather than the full Multimedia object deliberately: this is a rates surface, not a content surface, and shipping the full media object – id, descriptions, every delivery-URL variant – for every room type on every rate response would make the payload about images instead of about rates. The complete gallery is in Content.
The single best offer for this room – one entry, not a list of every rate and occupancy combination. Repeated rather than singular so that a room whose rate WAS computed but is not bookable (occupancy mismatch, sold out) can still report it, rather than vanishing from the results.
EMPTY, not a single unavailable entry, when the room type has no priced rate to report at all – master rates exist but none priced for these dates. That case has nothing meaningful to distinguish one property’s placeholder from another’s on a page ranking hundreds of them, so it is omitted rather than published as an all-blank entry.
Unavailable-but-computed offers sort last, never first: they report 0 across all amounts, so ordering purely by price would put “not priced” ahead of the cheapest real rate. For every rate and occupancy combination, call Inventory.
object
Stable identifier for this offer, and the id you carry into a booking.
This IS the master rate identifier — it maps from roomRateIdentifier, whose own schema calls it
“Specified master rate identifier”. The name says room_rate for historical reasons and is kept rather
than duplicated: publishing a second master_rate_id field with the same value would be two
representations of one thing that can disagree, which this API forbids elsewhere for prices.
The rate plan this offer sells under. Resolve it with Content’s GetRatePlan; a rate plan is shared by many offers, so it is referenced rather than repeated on each one.
True if THIS offer, at the requested occupancy, is bookable for the itinerary. Narrower than
PropertySearchResult.available, which is true when ANY offer at the property is. An unavailable offer is
still returned rather than dropped, so you can show the traveller why it cannot be booked.
Check-in date, ISO-8601 “YYYY-MM-DD”.
Check-out date, ISO-8601 “YYYY-MM-DD”.
Nights covered by this rate.
Adults the rate is priced for, after the property’s occupancy policy is applied.
Children the rate is priced for, after the property’s occupancy policy is applied.
ONE room, whole stay, BEFORE discounts — step 1 above. The “was” price: render it struck through next
to unit_price.
GUARANTEED >= unit_price. Occupancy surcharges and rate premiums are already inside it, so the gap
between the two is only ever the discounts. Equal to unit_price when nothing is discounted, in which
case show no strikethrough.
ONE room, whole stay, after every adjustment — step 2 above. The “now” price, and the figure the discount is measured against. Excludes the rate plan’s fixed charges.
Not named net or source_total: everywhere else in this platform “source” means the PROPERTY’S OWN
CURRENCY, and this figure is in the caller’s. Reusing the word would have the next mapper author reach
for the domain’s getSourceTotal() and quote the wrong currency.
ONE room, whole stay — fixed charges attached to the rate plan, a one-time cleaning fee and the like. Reported separately so a traveller sees them as their own line rather than as an unexplained difference. NEVER discounted, which is why they sit outside both prices above. Zero when the rate plan has none.
What the guest pays for every room: (unit_price + unit_extra_charges) x quantity. This is the number
to show and the number to charge.
Only meaningful when available is true. An unavailable offer reports 0 across every amount, which
means “not priced” rather than “free” — show the offer with its reason, never with a price of zero.
Meals included in the rate. These change which offer a traveller picks, so they are here rather than behind an identifier.
object
Breakfast included.
Brunch included.
Lunch included.
Dinner included.
All meals included.
All meals plus alcohol included.
True if the stay can be cancelled without charge before the policy’s deadline.
How many days from TODAY the traveller has left to cancel free of charge, and -1 when the rate is not refundable at all. Zero means the free-cancellation window closes today.
Derived as (days until check-in) − (the policy’s days-before-arrival deadline), floored at 0 — the same
calculation RoomTypeBestPriceForDateRange publishes. It is relative to the moment of the response and
will drift as the stay approaches, so treat it as display data, not something to cache.
Cancellation policy identifier. Join to Content for the full terms and wording.
Identifiers of the perks bundled with this rate. Join to Content for their names and descriptions. There is deliberately no monetary “perk value” on this surface.
How many identical rooms this offer is priced for — the quantity you set on the matching
RoomConfiguration. At least 1. What the PROPERTY has left is rooms_left, which is a different
number entirely.
It is echoed back because it is a MULTIPLIER on total, not merely a restatement of your request:
without it you cannot tell whether total covers one room or five. It can also change the unit price
itself, since a property may attach a rate to a room-count range — book three and every room may be
cheaper than booking one.
The saving as a fraction of unit_strikethrough_price — 0.15 for 15%. Zero when nothing is
discounted.
Published rather than left to you because there is one correct rounding of it and several plausible ones, and a paid API where two integrators compute “18%” and “17%” from the same response is a support burden rather than a saving. Quantity-invariant: discounting every room equally does not change the percentage.
Every adjustment that moved this rate away from the property’s plain price, one entry per kind, for showing a traveller WHY the number is what it is. Empty when nothing applied.
These reconcile exactly: the signed amounts sum to unit_price minus the property’s unadjusted price.
They are per-unit, like the prices they explain.
One reason this rate differs from the property’s plain price.
SIGNED, and the sign is the whole point: unit_amount is negative for anything that lowered the price
and positive for anything that raised it, so a caller can render a list of lines and add them up without
knowing which types are discounts. Amounts are per-unit minor units, matching the prices they explain.
The surcharges and premiums here are already inside unit_strikethrough_price, and the discounts are
the gap between it and unit_price. This message explains the arithmetic; it does not add to it.
object
What kind of adjustment this is.
How much it moved the price for ONE room over the whole stay, in minor units. Negative lowered the price, positive raised it. Never zero — an adjustment that changed nothing is not returned.
The property’s own wording for the promotion or premium in force, in English plus your requested language. Empty when neither applies.
At the RATE level, not on each adjustment, because that is how the platform stores it — one list of
descriptions covering the special rates that fired. Attaching a label to each PriceAdjustment would
have meant publishing a field nothing could ever fill.
A short piece of localized text.
The API returns descriptions already filtered to the language on your request, so you will normally see
exactly one entry per collection. language_code is still present so you can tell which language you got when
the requested one was unavailable and the property’s default was substituted.
object
Short label for this description.
The description body.
ISO 639-1 language code of name and description.
Promotional codes that were actually ACCEPTED and are reflected in the price above — not the codes you sent. A code your account is not entitled to is ignored rather than rejected, so comparing this against what you submitted is how you tell which ones bit.
How many rooms the property still has for the WHOLE stay — the “only 2 left” number.
The SMALLEST nightly allotment across the stay, not the first night’s and not an average. A three-night stay whose middle night has two rooms free has two rooms left, however many are free either side: you cannot sell a third room a guest would be evicted from on night two. The check-out date is excluded, since nobody occupies a room that night.
NOT the same as quantity, which is how many rooms YOU asked for. The relationship is
rooms_left >= quantity whenever available is true — an offer that cannot house the party you
requested is not bookable and says so. Reading quantity as “what the property has” overstates
availability, which is why they are named as differently as they are.
Zero means none are free for these dates, and only ever appears alongside available = false. It is
a real answer, not a missing one.
This is the property’s true position, not a banded or capped figure. Treat it as commercially sensitive: it is exact enough to reconstruct a property’s booking curve if sampled over time.
How many extras – add-ons plus in-room ancillaries – can be bought alongside this offer. Zero when it sells none.
A COUNT, not the items. Search is a list surface: the count is enough to render “3 extras available”
and decide whether to show a badge, and that is the only add-on decision a result row makes. The items
themselves are per-offer objects with their own prices and booking identifiers, which is a detail-view
payload – fetch them from Inventory, where RoomRate.add_on_ids and RoomRate.room_type_ancillaries
carry the full picture.
The two kinds are summed rather than reported separately because nothing you can do with this number
on a search row distinguishes them. They ARE different at booking time – an ancillary quotes this
rate’s room_rate_id as its inventory id, an add-on does not – and that difference is exactly why
resolving them belongs to the surface that can act on it.
The property’s own display order for its room types, ascending, when it has expressed one; 0 when it has not. This describes the ROOM, which is why it is here rather than on each rate – the domain defines it as “how the room types should be sorted and displayed”.
It is a merchandising hint, not the delivered order: room_types is already ordered by price.
Every perk referenced by any RoomRate.perk_ids above, deduplicated — one entry per distinct perk,
not one per rate. Resolve a perk id here rather than calling Content; a handful of distinct perks
typically cover every rate in this response.
A perk bundled with a rate.
Lives here rather than in partner_content.proto because the PRICING surfaces return a deduplicated
dictionary of these alongside their rates: RoomRate.perk_ids would otherwise be unresolvable without a
second call, and inlining the perk on every rate would repeat a handful of distinct perks across every
rate of every room type of every property in a search result.
descriptions carries the display name and body together — Description has both.
object
Stable perk identifier. Matches an entry in RoomRate.perk_ids.
Localized name and description, in English plus your requested language.
A short piece of localized text.
The API returns descriptions already filtered to the language on your request, so you will normally see
exactly one entry per collection. language_code is still present so you can tell which language you got when
the requested one was unavailable and the property’s default was substituted.
object
Short label for this description.
The description body.
ISO 639-1 language code of name and description.
Whether the perk is guaranteed rather than subject to availability.
Perk tier; higher is more valuable.
Display order, ascending.
Commission rate your account earns on this property, as a fraction — 0.15 for 15%. A property-channel term rather than a per-rate one: it describes your commercial relationship with the property, so it holds for every offer below.
A double rather than a float because this multiplies money. 0.15 has no exact binary representation,
and the wider type keeps the error far enough below a minor unit that total * commission does not
drift into a visible discrepancy on large bookings.
True if this is direct inventory, with no intermediary between you and the property.
True if AT LEAST ONE room type at this property is bookable for the itinerary. Per-room-type
availability is RoomPrice.available; this is the “is anything here bookable at all” flag. When false,
prices still carries the unavailable offers rather than being empty, so you can show why.
Zero-based index of this page.
Requested page size.
Total matching properties across all pages.
Total number of pages.
Properties on this page. Differs from size on the last page.
True if this is the first page.
True if this is the last page.
ISO 4217 currency EVERY amount in this response is denominated in — the one you asked for in
user_session.currency_code, or the property’s own when you asked for none. Stated once here rather than
repeated on every amount, which is why the amounts themselves are bare integers.
How many decimal places currency_code has: 2 for THB and USD, 0 for JPY, KRW and VND.
Amounts are integers in MINOR UNITS, so the real value is amount / 10^currency_exponent. This is
published rather than assumed because a fixed divide-by-100 is wrong for a real slice of Wink’s
inventory — a JPY stay priced at 15000 is ¥15,000, not ¥150.
ISO 639-1 language the names and other text in this response are in — the one you asked for in
user_session.language_code, or English when it was unavailable.
Example
{ "page": { "content": [ { "roomTypes": [ { "rates": [ { "adjustments": [ { "type": "ADJUSTMENT_TYPE_UNSPECIFIED" } ] } ] } ] } ] }}