---
updatedAt: 2026-09-30T17:26:32.000Z
agentTools:
  projectIndex: https://open-api-docs.guesty.com/llms.txt
---

# Searching for Available Listings and All Listings

How to use the listings endpoint to return a curated collection of listing objects.

## Overview

<br />

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.

<br />

### Endpoint Overview

<br />

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

<br />

```json
Authorization: Bearer YOUR_API_TOKEN
```

<br />

### Query Parameters

<br />

For a complete list of query parameters and their descriptions, please refer to <Anchor target="_blank" href="https://open-api-docs.guesty.com/reference/propertiesListingList">Retrieve all listings</Anchor>. The following table highlights the query parameters to include, should you wish to differentiate between active/inactive and listed/unlisted listings.

<br />

| Query Parameter | Type    | Description                                                                                                                                                                                                                                         |
| :-------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `active`        | boolean | `true` for active, or `false` for inactive.                                                                                                                                                                                                         |
| `pms.active`    | boolean | Only use this if your active listing isn't returned with the `active` parameter. <Anchor target="_blank" href="https://help.guesty.com/hc/en-gb/articles/9370047984413-Contacting-Customer-Experience">Contact Customer Experience</Anchor> to fix. |
| `listed`        | boolean | `true` for listed, or `false` for unlisted.                                                                                                                                                                                                         |

<br />

### Dual Functionality

<br />

This endpoint serves two primary purposes:

1. Searching for available listings within a specific date range (as part of a <Anchor target="_blank" href="https://open-api-docs.guesty.com/docs/reservations-v3-booking-flow#step-1-discovery">booking flow</Anchor>).
2. Retrieving all listings regardless of availability.

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

<br />

## Searching for Available Listings

<br />

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

<br />

| Query Parameter          | Type    | Description                                                                                                         |
| :----------------------- | :------ | :------------------------------------------------------------------------------------------------------------------ |
| `available`              | object  | Denotes an available listings query.                                                                                |
| `available.checkIn`      | string  | Check-in date in YYYY-MM-DD format.                                                                                 |
| `available.checkOut`     | string  | Check-out date in YYYY-MM-DD format                                                                                 |
| `available.minOccupancy` | integer | The total number of people the property can accommodate. Returns listings that match the occupancy value or higher. |

<br />

#### 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.

<br />

```curl
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}'
```

<br />

Learn more about the available listing search in our <Anchor target="_blank" href="https://open-api-docs.guesty.com/docs/available-listings">Query Available Listings</Anchor> guide.

<br />

## Retrieving All Listings

<br />

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

<br />

#### Example:

<br />

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

<br />

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

<br />

### Response Structure

<br />

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

<br />

#### Example Response:

<br />

```json
{
  "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
}
```

<br />

### Identifying Available Fields

<br />

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 <Anchor target="_blank" href="https://open-api-docs.guesty.com/reference/propertiesListingList">Retrieve all listings</Anchor> document and make a request to <Anchor target="_blank" href="https://open-api-docs.guesty.com/reference/propertiesListingGet">Retrieve a listing</Anchor> 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.

<br />

#### Example Workflow:

<br />

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:

<br />

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

<br />

4. Use this in your listings request:

<br />

```
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
```

<br />

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

<br />

Remember, while the documentation provides a comprehensive overview, the available fields may 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.

<br />

## Common Use Cases and Examples

<br />

1. **Search for Available Listings in a Specific Date Range**

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

<br />

```curl
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}'
```

<br />

2. **Search for Listings That Can Accommodate Large Groups**

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

<br />

```curl
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}'
```

<br />

3. **Search for Luxury Listings**

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

<br />

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

<br />

4. **Search for Recently Added Listings**

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

<br />

```curl
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}'
```

<br />

5. **Search for Available Listings with Specific Amenities**

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

<br />

```curl
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}'
```

<br />

6. **Search for Listings in a Specific Location**

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

<br />

```curl
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}'
```

<br />

or

<br />

```curl
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}'
```

<br />

7. **Search for Multi-Units**

<br />

```curl
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}'
```

<br />

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

<br />

```curl
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}'
```

<br />

## Searching Using Predetermined Views

<br />

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.

<br />

### Creating Views

<br />

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 <Anchor target="_blank" href="https://help.guesty.com/hc/en-gb/articles/9370036475293-Setting-up-a-properties-report">Guesty help article on setting up property reports</Anchor>.

2. **API View Endpoint**: You can programmatically create views using the POST /views endpoint. Refer to the <Anchor target="_blank" href="https://open-api-docs.guesty.com/reference/accountsViewCreate">Create a view</Anchor> endpoint documentation for more information.

<br />

### Using Views in Listing Searches

<br />

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

<br />

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

<br />

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

<br />

## Best Practices

<br />

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.

<br />

## Conclusion

<br />

The <Anchor target="_blank" href="https://open-api-docs.guesty.com/reference/propertiesListingList">Retrieve all listings</Anchor> 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.