GUguesty
Listings

List listings

Changed on

Retrieve the listings on your account as a paginated result set carrying results, fields and limit. Combine the filter parameters to narrow the set, or pass viewId to apply the filters, fields and sort order saved in a view.

get/listings

Request

  • Base URL
    https://open-api.guesty.com/v1
  • URL
    https://open-api.guesty.com/v1/listings
  • Auth
    API key in header authorization

Query parameters

idsstring
Example:3847fh87hs78n79f3,fj78fh78fbw7yyhdfyb

Limit results to these ids, comma separated

nidsstring
Example:3847fh87hs78n79f3,fj78fh78fbw7yyhdfyb

Limit results to not include these ids, comma separated

viewIdstring
Example:Cozy luxurious

Retrieve a specific saved listings view (a view is a saved custom report)

qstring

Search query string. Searches in title, internalNote, address.full

citystring

Limit results to city

activeboolean

Limit results to active state. Boolean, true for only active, false for only inactive, don't include for all.

pmsActiveboolean

Limit results to listings with the feature pms active. Boolean, true for only active, false for only inactive, don't include for all.

integrationIdstring

Limit results to specific integration

listedboolean

Limit results to listed state. Boolean, true for only listed, false for only unlisted, don't include for all.

checkInstring
checkOutstring
minOccupancynumber

Limit results to only available listings in specific dates

IMPORTANT NOTE: Fields in this query must be enclosed in curly braces as shown below, and NOT as displayed in the coding playground output. available = {"checkIn":"YYYY-MM-DD","checkOut":"YYYY-MM-DD","minOccupancy":3}

{
  "checkIn": "2022-12-27",
  "checkOut": "2022-12-29",
  "minOccupancy": 3
}
ignoreFlexibleBlocksboolean

Shows available listings and listings with flexible blocks.

tagsstring
Example:tags=kinesu

Limit results to listings with specific tag

fieldsstring
Example:title address

Selection of fields, separated by space

sortstring
Example:title/-title

ascending alphabetical sort, use '-' for descending sort

limitnumber

Pagination, max: 100

skipnumber

Pagination skip

Response

Listings Array

_idstring

Unique Guesty listing ID.

accountIdstring

Unique Guesty account ID.

createdAtstring
isVirtualboolean
nicknamestring
tagsstring[]
isListedboolean
titlestring
propertyTypestring
roomTypestring
bedTypestring
accommodatesnumber
bedroomsnumber
areaSquareFeetnumber
timezonestring
defaultCheckInTimestring
defaultCheckOutTimestring
amenitiesstring[]

Array of amenities. Use the amenities endpoints to review and manage this list.

amenitiesNotIncludedstring[]

Array of amenities not included. Use the amenities endpoints to review and manage this list.

netIncomeFormulastring
commissionFormulastring
commissionTaxPrecentagestring
activeboolean
customFieldsobject
calendarRulesobject
publicDescriptionobject
privateDescriptionobject
markupsobject
isTestboolean

Marks the listing as a test property. Test property titles must include the 'Test_' prefix. Only SINGLE-type listings can be selected.

Example response

[
  {
    "_id": "59ac245d27cb310f0017afe3",
    "accountId": "59ac245d27cb310f0017afe3",
    "createdAt": "2017-09-03T15:48:45.070Z",
    "integrations": [
      {
        "_id": "5958c7e5884e961000817799",
        "airbnb2": {
          "ignored": {
            "reservations": [],
            "listings": []
          },
          "emailsFromSupport": []
        },
        "nickname": "naama",
        "id": "naama@user.guesty.com",
        "userId": "563e0b6a08a2710e00057b85",
        "accountId": "563e0b6a08a2710e00057b82"
      }
    ],
    "address": {
      "full": "Kaplan St 2, Ramat Gan, Israel",
      "lng": 34.8202173,
      "lat": 32.0695525
    },
    "publishedAddress": {
      "full": "Kaplan St 2, Ramat Gan, Israel",
      "lng": 34.8202173,
      "lat": 32.0695525
    },
    "cleaningStatus": {
      "updatedAt": "2019-08-24T14:15:22Z"
    },
    "picture": {
      "thumbnail": "https://res.cloudinary.com/guesty/image/upload/c_fit,h_200/v1659982852/staging6/5213a2d206112710005d96ff/gglflnes8vodgkmtm08c.jpg",
      "large": "https://res.cloudinary.com/guesty/image/upload/c_fit,w_756/v1659982852/staging6/5213a2d206112710005d96ff/gglflnes8vodgkmtm08c.jpg",
      "caption": "Living room",
      "height": 756,
      "original": "https://res.cloudinary.com/guesty/image/upload/v1659982852/staging6/5213a2d206112710005d96ff/gglflnes8vodgkmtm08c.jpg",
      "size": 39516,
      "width": 756
    },
    "pictures": [
      {
        "thumbnail": "https://res.cloudinary.com/guesty/image/upload/c_fit,h_200/v1659982852/staging6/5213a2d206112710005d96ff/gglflnes8vodgkmtm08c.jpg",
        "large": "https://res.cloudinary.com/guesty/image/upload/c_fit,w_756/v1659982852/staging6/5213a2d206112710005d96ff/gglflnes8vodgkmtm08c.jpg",
        "caption": "Living room",
        "height": 756,
        "original": "https://res.cloudinary.com/guesty/image/upload/v1659982852/staging6/5213a2d206112710005d96ff/gglflnes8vodgkmtm08c.jpg",
        "size": 39516,
        "width": 756
      }
    ],
    "terms": {
      "minNights": 1,
      "maxNights": 30,
      "cancellation": "STANDARD"
    },
    "prices": {
      "guestsIncludedInRegularFee": 6,
      "extraPersonFee": 55.5,
      "monthlyPriceFactor": 0.9,
      "weeklyPriceFactor": 0.9,
      "weekendBasePrice": 150,
      "securityDepositFee": 100,
      "cleaningFee": 50
    },
    "pms": {
      "cleaningStatus": {
        "updatedAt": "2019-08-24T14:15:22Z"
      }
    }
  }
]

Changes

  • 3122b8618183Revision changes
    • breaking

      the /// response's property type changed from integer to string for status

    • info

      api operation id propertiesListingList was added

    • info

      added the optional property / to the response with the status

    • info

      the // response's property pattern ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$ was added for the status