GET # Marriott Bonvoy Search API Search for Marriott Bonvoy hotels by geographic coordinates with real-time availability and pricing. ## Overview #### Coordinate-Based Search This endpoint searches by latitude and longitude, making it ideal for map-based applications and proximity searches. The Marriott Bonvoy Search endpoint returns hotels near a geographic location with real-time pricing, brand information, ratings, and distance from the search center. Supports pagination, sorting, and currency selection. ### Endpoint URL GET https://api.stayapi.com/v1/marriott/bonvoy/search ## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | latitude | float | Required | Latitude of search center (-90 to 90) | | longitude | float | Required | Longitude of search center (-180 to 180) | | check\_in | string | Required | Check-in date in YYYY-MM-DD format | | check\_out | string | Required | Check-out date in YYYY-MM-DD format | | adults | integer | Optional | Number of adults (1-10). Default: 2 | | rooms | integer | Optional | Number of rooms (1-8). Default: 1 | | currency | string | Optional | Currency code (e.g., USD, EUR, GBP). Default: USD | | offset | integer | Optional | Pagination offset. Default: 0. For the next page, use page\_info.next\_offset from the previous response. | | limit | integer | Optional | Results per page (max 20). Default: 20 | | sort\_by | string | Optional | Sort field (DISTANCE or PRICE). Default: DISTANCE | | corporate\_code | string | Optional | Corporate or promotional rate code (e.g., MMP, AAA). Marriott silently ignores invalid codes. See [Corporate rates](#corporate-rates). | | corporate\_only | boolean | Optional | Return only hotels that have a rate under `corporate_code`, priced at that rate. Requires `corporate_code`. Default: false | #### Finding Coordinates Use Google Maps or a geocoding service to get latitude and longitude for your target location. For example, Bangkok is approximately 13.7563, 100.5018. ## Corporate Rates - **`corporate_code` alone:** hotels with a rate under the code are priced at that rate, but hotels without one still appear at their regular lowest price. The response does not say which hotels the code applied to. - **`corporate_code` with `corporate_only=true`:** only hotels with a rate under the code are returned, and `price` is that rate. Hotels without a rate under the code are left out. The response shape is unchanged. - `corporate_only=true` without `corporate_code` returns 400 `INVALID_PARAMETERS`. - When a code covers several rate plans, `price` is the lowest of them and the response does not say which plan it came from. See [Codes that cover several rate plans](/docs/endpoints/marriott-bonvoy/price-calendar#multi-plan-codes). #### Flexible dates To find the cheapest dates rather than the cheapest hotel for fixed dates, collect property\_id values here and request a Price Calendar for each one with the same corporate\_code. See the [flexible dates recipe](/docs/endpoints/marriott-bonvoy/price-calendar#flexible-dates) on the Price Calendar page. ## Response Format The response includes a list of Marriott hotels with pricing, brand details, ratings, and distance from the search coordinates. ### Response Structure - **success** : Boolean indicating request success - **hotels** : Array of hotel objects - **total** : Total number of matching hotels - **page\_info** : Pagination metadata (has\_next\_page, has\_previous\_page, next\_offset, current\_offset) ### Pagination - **has\_next\_page** (boolean): Whether another page is available - **has\_previous\_page** (boolean): Whether a previous page is available - **next\_offset** (integer or null): Offset for the next request; null on the last page - **current\_offset** (integer): Offset of the current page Start with `offset=0` and a `limit` of up to 20. While `page_info.has_next_page` is true, pass `page_info.next_offset` as the next request's `offset`, keeping the other search parameters unchanged. Stop when `has_next_page` is false. The `offset` and `limit` fields are request parameters. ## Hotel Object Fields | Field | Type | Description | | --- | --- | --- | | property\_id | string | Marriott property code (e.g., "BKKDT", "LAXJW") | | name | string | Hotel name | | brand | object | Brand details (id, name) e.g., "JW Marriott", "The Ritz-Carlton" | | location | object | GPS coordinates (latitude, longitude) | | description | string | Hotel description | | rating | float | Guest rating score | | review\_count | integer | Total number of reviews | | image | string | Primary hotel image URL | | url | string | Marriott.com hotel page URL | | bookable | boolean | Whether the property has available rooms | | price | object | Pricing details (per\_night, total, taxes, fees, currency, points\_per\_night) | | distance\_meters | float | Distance from search center in meters | ## Error Responses The API returns standard HTTP error codes with detailed error messages following the RFC 7807 Problem Details format. ### 400 Bad Request Invalid request parameters (e.g., invalid dates, out-of-range coordinates, or `corporate_only` without `corporate_code`) ``` { "type": "https://api.stayapi.com/errors/invalid-dates", "title": "Invalid Dates", "status": 400, "detail": "Check-out date must be after check-in date" } ``` ### 502 Bad Gateway Upstream service error from Marriott ``` { "type": "https://api.stayapi.com/errors/upstream-error", "title": "Upstream Error", "status": 502, "detail": "The upstream service could not complete the request." } ``` ## Usage Tips ### Best Practices - Use precise coordinates for best results (e.g., city center or airport location) - Dates must be in YYYY-MM-DD format and check-in cannot be in the past - Use `offset` and `limit` for pagination through large result sets - The `property_id` field can be used with the Rooms endpoint to get detailed rates - Sort by PRICE to find the cheapest options first - Pass a `property_id` to the Price Calendar endpoint to compare the lowest rate across up to 36 check-in dates - The `distance_meters` field helps rank results by proximity #### Rate Limiting This endpoint is subject to your plan's rate limits. Each search counts as one API call regardless of the number of results returned. ## Related Endpoints ### Marriott Bonvoy Rooms Get room types and rates for a specific Marriott property [View Documentation →](/docs/endpoints/marriott-bonvoy/rooms) ### Marriott Bonvoy Price Calendar Lowest rate per check-in date for one property, including corporate and points calendars [View Documentation →](/docs/endpoints/marriott-bonvoy/price-calendar) ### Meta Search Search across multiple booking platforms [View Documentation →](/docs/endpoints/meta-search) Request ```curl curl -X GET "https://api.stayapi.com/v1/marriott/bonvoy/search?latitude=13.7563&longitude=100.5018&check_in=2026-11-10&check_out=2026-11-13&adults=2¤cy=USD" \ -H "X-API-Key: YOUR_API_KEY" ``` Response ```json { "success": true, "hotels": [ { "property_id": "BKKDT", "name": "JW Marriott Hotel Bangkok", "brand": { "id": "JW", "name": "JW Marriott" }, "location": { "latitude": 13.7440, "longitude": 100.5494 }, "description": "Luxury hotel in the heart of Bangkok with world-class dining and spa facilities.", "rating": 4.5, "review_count": 2847, "image": "https://cache.marriott.com/content/dam/marriott-renditions/BKKDT/bkkdt-exterior-0001-hor-wide.jpg", "url": "https://www.marriott.com/hotels/travel/bkkdt-jw-marriott-hotel-bangkok/", "bookable": true, "price": { "per_night": 185.00, "total": 555.00, "taxes": 55.50, "fees": 0, "currency": "USD", "points_per_night": 35000 }, "distance_meters": 1250.5 } ], "total": 42, "page_info": { "has_next_page": true, "has_previous_page": false, "next_offset": 20, "current_offset": 0 } } ``` ```json { "type": "https://api.stayapi.com/errors/invalid-date-format", "title": "Invalid Date Format", "status": 400, "detail": "Date must be in YYYY-MM-DD format", "instance": "/v1/marriott/bonvoy/search", "provider": "marriott", "product": "bonvoy", "error_code": "INVALID_DATE_FORMAT", "correlation_id": "req_abc123" } ```