Searching for Available Listings and All Listings

Overview

The Guesty API's GET /listings endpoint is a powerful tool for retrieving listing information. This guide will help you understand how to use this endpoint effectively, covering both searching for available listings and retrieving all listings.

Endpoint Overview

• URL: GET https://open-api.guesty.com/v1/listings
• Authentication: Bearer Token (your API token)

Authorization: Bearer YOUR_API_TOKEN

Query Parameters

For a complete list of query parameters and their descriptions, please refer to Retrieve all listings. The following table highlights the query parameters to include should you wish to differentiate between active/inactive and listed/unlisted listings.

Dual Functionality

This endpoint serves two primary purposes:

1. Searching for available listings within a specific date range (as part of a booking flow).
2. Retrieving all listings regardless of availability.

The presence of the available parameter determines which function is activated.

Searching for Available Listings

To find listings available for a specific date range, include the available object with the required sub-parameters.

Example:

This request will return up to 50 available listings for the specified date range that can accommodate at least 3 guests, sorted by _id in descending order.

curl --globoff 'https://open-api.guesty.com/v1/listings?available={"checkIn":"2023-07-01","checkOut":"2023-07-15","minOccupancy":3}&limit=50&fields=title price pictures&sort=-_id' \
--header 'Authorization: Bearer {YOUR_API_TOKEN}'

Learn more about available listing search in our Query Available Listings guide.

Retrieving All Listings

To get all listings regardless of availability, omit the available parameter.

Example:

curl 'https://open-api.guesty.com/v1/listings?limit=50&fields=title%20address%20accommodates&sort=-createdAt' \
--header 'Authorization: Bearer {YOUR_API_TOKEN}'

This request will return up to 50 listings, sorted by creation date in descending order.

Response Structure

The API returns a JSON object containing:

• results: An array of listing objects
• count: Total number of results
• limit: Number of results per page
• skip: Number of results skipped

Example Response:

{
  "results": [
    {
      "title": "Cozy Downtown Apartment",
      "price": 150,
      "pictures": [
        {"thumbnail": "https://example.com/thumb.jpg", "regular": "https://example.com/regular.jpg"}
      ]
    },
    // More listing objects...
  ],
  "count": 100,
  "limit": 50,
  "skip": 0
}

Identifying Available Fields

To determine which fields you can request, you have several options:

1. Consult the API Documentation: Review the response schema and example response in the Retrieve all listings document and make a request to Retrieve a listing to see all fields for a specific listing.

2. Examine the Response: Make a request to the listings endpoint and analyze the returned fields.

3. Create and Test Your Fields List: Based on the schema, example response, and any single listing requests, create a list of fields you're interested in. Test this list using the 'fields' parameter in the listings endpoint.

Example Workflow:

1. Review the schema and example response in the API documentation.

2. Based on this review, you might identify fields like: _id, title, description, address.full, address.city, address.country, pictures, amenities, accommodates, bedrooms, or bathrooms, etc.

3. Create a fields list:

fields=id title description address.full address.city address.country pictures amenities accommodates bedrooms bathrooms

4. Use this in your listings request:

GET https://open-api.guesty.com/v1/listings?limit=10&fields=id title description address.full address.city address.country pictures amenities accommodates bedrooms bathrooms

5. Adjust your fields list based on the results and your specific needs.

Remember, while the documentation provides a comprehensive overview, the available fields may be subject to change. It's good practice to periodically review the documentation and test your requests to ensure you work with the most up-to-date field list.

Common Use Cases and Examples

1. Search for Available Listings in a Specific Date Range

Use case: Find all available listings for a summer vacation in July

curl --globoff 'https://open-api.guesty.com/v1/listings?available={"checkIn":"2025-07-01","checkOut":"2025-07-15","minOccupancy":2}&limit=50&fields=title price pictures&sort=-_id' \
--header 'Authorization: Bearer {YOUR_API_TOKEN}'

2. Search for Listings That Can Accommodate Large Groups

Use case: Find listings that can host a family reunion for 10 people.

curl 'https://open-api.guesty.com/v1/listings?limit=20&fields=title accommodates bedrooms bathrooms&filters=[{"operator": "$gte", "field": "accommodates", "value": 10}]&sort=-_id' \
--header 'Authorization: Bearer {YOUR_API_TOKEN}'

3. Search for Luxury Listings

Use case: Find high-end listings for a premium vacation experience.

curl 'https://open-api.guesty.com/v1/listings?limit=10&fields=title price amenities&tags=lux&sort=-_id' \
--header 'Authorization: Bearer {YOUR_API_TOKEN}'

4. Search for Recently Added Listings

Use case: Discover the newest listings added to the platform.

curl 'https://open-api.guesty.com/v1/listings?limit=30&fields=title createdAt pictures&filters=[{"operator": "$gte", "field": "createdAt", "value": "2025-01-07T14:46:27.000Z"}]&sort=-createdAt' \
--header 'Authorization: Bearer {YOUR_API_TOKEN}'

5. Search for Available Listings with Specific Amenities

Use case: Find available listings with a pool for a summer getaway.

curl --globoff 'ttps://open-api.guesty.com/v1/listings?available={"checkIn"=2025-08-01&checkOut=2025-08-07&limit=20&fields=title amenities price&filters={"amenities":{"@in":["Swimming+pool","Bathtub"]}}&sort=_id' \
--header 'Authorization: Bearer {YOUR_API_TOKEN}'

6. Search for Listings in a Specific Location

Use case: Find all listings in New York City for a city break.

curl 'https://open-api.guesty.com/v1/listings?limit=50&fields=title address price&city=New York City&sort=_id' \
--header 'Authorization: Bearer {YOUR_API_TOKEN}'

or

curl 'https://open-api.guesty.com/v1/listings?limit=50&fields=title address price&q=New York City&sort=_id' \
--header 'Authorization: Bearer {YOUR_API_TOKEN}'

7. Search for Multi-Units

curl --globoff 'https://open-api.guesty.com/v1/listings?limit=20&fields=title accommodates mtl&filters={"type":{"@eq":"MTL"}}&sort=-_id' \
--header 'Authorization: Bearer {YOUR_API_TOKEN}'

8. Search for Sub-units of a Specific Multi-unit

curl --globoff 'https://open-api.guesty.com/v1/listings?limit=20&fields=title nickname accommodates mtl&filters={"type":{"@eq":"MTL_CHILD"},"mtl.p":{"@in":["MTL_LISTING_ID"]}}&sort=-_id' \
--header 'Authorization: Bearer {YOUR_API_KEY}'

Searching Using Predetermined Views

In addition to query parameters, you can search listings using predetermined filtered views. This approach uses the viewId parameter and can be handy for frequently used filters or complex queries.

Creating Views

There are two ways to create views:

1. User Dashboard: You can create and manage views in your Guesty dashboard. For detailed instructions, see the Guesty help article on setting up property reports.

2. API View Endpoint: You can programmatically create views using the POST /views endpoint. Refer to the Create a view endpoint documentation for more information.

Using Views in Listing Searches

Once you have created a view, you can use its ID in your listing searches:

curl 'https://open-api.guesty.com/v1/listings?viewId=YOUR_VIEW_ID' \
--header 'Authorization: Bearer {YOUR_API_TOKEN}'

Replace YOUR_VIEW_ID with the actual ID of your created view.

This approach allows you to:

• Simplify complex queries
• Maintain consistent filters across multiple requests
• Quickly switch between different predefined listing subsets

Best Practices

1. Use the fields parameter to optimize your request by only retrieving necessary data. Separate field names with spaces.
2. Implement pagination using limit and skip for large result sets.
3. Utilize the sort parameter to order results based on your needs. Use a unique identifier such as _id to retain results order and return unique results.
4. When searching for available listings, always include the available parameter with checkIn, checkOut, and minOccupancy sub-parameters.
5. Regularly review the API documentation for updates to available fields and functionality.

Conclusion

The Retrieve all listings endpoint is a versatile tool for retrieving listing information. By understanding its dual functionality and mastering its parameters, you can efficiently search for available properties or manage your entire listing inventory. Remember to tailor your requests to your specific needs and always adhere to the latest API documentation for the best results.