Property Location & Details

Overview

Hosts must provide an accurate address to avoid any problems for guests locating and arriving at their stay. Several different parameters define it:

The latitude and longitude
The country code, state, and city
The zip code, street, and apartment number

🚧
Address Change Notice
Guesty synchronizes the listing address with supported booking channels. However, once guests have stayed at the listing, or if the listing has upcoming reservations, you may need to contact their Support to change the location. See our Help Center for more details.

Retrieving the Property's Address

Available Endpoints

Method	Endpoint
GET	/listings/{id}?fields=address publishedAddress

Key Parameters

Path Parameter	Type	Description	Required
`id`	string	The property ID.	✔️

Query Parameter	Type	Description	Required
`fields`	string	Specify the fields to return for a focused response. For the address, specify `address` and `publishedAddress`.

Example

You can add any of the property fields you need to retrieve to obtain your objective. In addition to address and publishedAddress, nickname and type have been included to make identification of the property easier.

Request

curl 'https://open-api.guesty.com/v1/listings/{id}?fields=nickname%20type%20address%20publishedAddress'

var requestOptions = {
  method: 'GET',
  redirect: 'manual'
};

fetch("https://open-api.guesty.com/v1/listings/{id}?fields=nickname type address publishedAddress", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://open-api.guesty.com/v1/listings/{id}?fields=nickname%20type%20address%20publishedAddress',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => false,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import http.client

conn = http.client.HTTPSConnection("open-api.guesty.com")
payload = ''
headers = {}
conn.request("GET", "/v1/listings/{id}?fields=nickname%20type%20address%20publishedAddress", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Response

{
    "_id": "<listingId>",
    "type": "SINGLE",
    "tags": [],
    "nickname": "Autumn Estates",
    "address": {
        "full": "2365 Kalākaua Ave, Honolulu, HI 96815, United States",
        "street": "2365 Kalākaua Ave",
        "city": "Honolulu",
        "state": "HI",
        "country": "United States",
        "zipcode": "96815",
        "apt": "311",
        "lat": 21.29026939663333,
        "lng": -157.8259446530332
    },
    "accountId": "<accountId>",
    "publishedAddress": {
        "city": "Honolulu",
        "country": "United States",
        "full": "2365 Kalākaua Ave, Honolulu, HI 96815, United States",
        "lat": 21.29026939663333,
        "lng": -157.8259446530332,
        "state": "HI",
        "zipcode": "96815"
    }
}

Editing the Property Address

📘
Differentiating Between Address Objects
The address contains the property's exact location for sharing confirmed guests and within your organisation. You only need to describe the publishedAddress to have a more general location to increase the security of your property on booking channels.

Available Endpoints

Method	Endpoint
PUT	/listing/{id}

Key Parameters

Path Parameter	Type	Description	Required
`id`	string	The property's ID	✔️

Body Parameter	Type	Description	Required
`address`	object	The property's precise street address. See the following table.	✔️
`publishedAddress`	object	The property's general street address. See the table below.

Address Object

Path Parameter	Type	Description	Required
`full`	string	The complete street address.
`street`	string	Street name and number.	✔️
`apt`	string	Apartment or unit number.
`city`	string	Name of the city within which the property is located.	✔️
`state`	string	The state or area within which the city is located.	✔️
`country`	string	Name of the country.	✔️
`zipcode`	string	The zip or postal code of the street address.	✔️
`lat`	string	The latitude coordinates of the location in decimal format.	✔️
`lng`	string	The longitude coordinates of the location in decimal format.	✔️

Published Address Object

Path Parameter	Type	Description	Required
`street`	string	Street name and number.	✔️
`apt`	string	Apartment or unit number.
`city`	string	Name of the city within which the property is located.
`state`	string	The state or area within which the city is located.
`country`	string	Name of the country.	✔️
`zipcode`	string	The zip or postal code of the street address.	✔️
`lat`	string	The latitude coordinates of the location in decimal format.	✔️
`lng`	string	The longitude coordinates of the location in decimal format.	✔️
`full`	string	The complete street address.

Example

Request

curl --request PUT 'https://open-api.guesty.com/v1/listings/{id}' \
--data '{
    "address": {
        "full": "Shlomo Ibn Gabirol St 69, Tel Aviv-Yafo",
        "street": "Shlomo Ibn Gabirol St 69",
        "city": "Tel Aviv-Yafo",
        "state": "Gush Dan",
        "zipcode": "6416201",
        "country": "Israel",
        "lat": 32.08195191116856,  
        "lng": 34.78085563274133 
    },
    "publishedAddress": {
        "full": "Shlomo Ibn Gabirol St 69, Tel Aviv-Yafo",
        "street": "Shlomo Ibn Gabirol St 69",
        "city": "Tel Aviv-Yafo",
        "state": "Gush Dan",
        "zipcode": "6416201",
        "country": "Israel",
        "lat": 32.08195191116856,  
        "lng": 34.78085563274133 
    }
}'

var raw = "{\n    \"address\": {\n        \"full\": \"Shlomo Ibn Gabirol St 69, Tel Aviv-Yafo\",\n        \"street\": \"Shlomo Ibn Gabirol St 69\",\n        \"city\": \"Tel Aviv-Yafo\",\n        \"state\": \"Gush Dan\",\n        \"zipcode\": \"6416201\",\n        \"country\": \"Israel\",\n        \"lat\": 32.08195191116856,  \n        \"lng\": 34.78085563274133 \n    },\n    \"publishedAddress\": {\n        \"full\": \"Shlomo Ibn Gabirol St 69, Tel Aviv-Yafo\",\n        \"street\": \"Shlomo Ibn Gabirol St 69\",\n        \"city\": \"Tel Aviv-Yafo\",\n        \"state\": \"Gush Dan\",\n        \"zipcode\": \"6416201\",\n        \"country\": \"Israel\",\n        \"lat\": 32.08195191116856,  \n        \"lng\": 34.78085563274133 \n    }\n}";

var requestOptions = {
  method: 'PUT',
  body: raw,
  redirect: 'manual'
};

fetch("https://open-api.guesty.com/v1/listings/64f03f9094d741004fda977d", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://open-api.guesty.com/v1/listings/64f03f9094d741004fda977d',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => false,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_POSTFIELDS =>'{
    "address": {
        "full": "Shlomo Ibn Gabirol St 69, Tel Aviv-Yafo",
        "street": "Shlomo Ibn Gabirol St 69",
        "city": "Tel Aviv-Yafo",
        "state": "Gush Dan",
        "zipcode": "6416201",
        "country": "Israel",
        "lat": 32.08195191116856,  
        "lng": 34.78085563274133 
    },
    "publishedAddress": {
        "full": "Shlomo Ibn Gabirol St 69, Tel Aviv-Yafo",
        "street": "Shlomo Ibn Gabirol St 69",
        "city": "Tel Aviv-Yafo",
        "state": "Gush Dan",
        "zipcode": "6416201",
        "country": "Israel",
        "lat": 32.08195191116856,  
        "lng": 34.78085563274133 
    }
}',
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import http.client

conn = http.client.HTTPSConnection("open-api.guesty.com")
payload = "{\n    \"address\": {\n        \"full\": \"Shlomo Ibn Gabirol St 69, Tel Aviv-Yafo\",\n        \"street\": \"Shlomo Ibn Gabirol St 69\",\n        \"city\": \"Tel Aviv-Yafo\",\n        \"state\": \"Gush Dan\",\n        \"zipcode\": \"6416201\",\n        \"country\": \"Israel\",\n        \"lat\": 32.08195191116856,  \n        \"lng\": 34.78085563274133 \n    },\n    \"publishedAddress\": {\n        \"full\": \"Shlomo Ibn Gabirol St 69, Tel Aviv-Yafo\",\n        \"street\": \"Shlomo Ibn Gabirol St 69\",\n        \"city\": \"Tel Aviv-Yafo\",\n        \"state\": \"Gush Dan\",\n        \"zipcode\": \"6416201\",\n        \"country\": \"Israel\",\n        \"lat\": 32.08195191116856,  \n        \"lng\": 34.78085563274133 \n    }\n}"
headers = {}
conn.request("PUT", "/v1/listings/64f03f9094d741004fda977d", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Response

{
    "address": {
        "full": "Shlomo Ibn Gabirol St 69, Tel Aviv-Yafo, Israel",
        "street": "Shlomo Ibn Gabirol Street 69",
        "city": "Tel Aviv-Yafo",
        "state": "Tel Aviv District",
        "country": "Israel",
        "zipcode": "6416201",
        "apt": "311",
        "lat": 32.0817299,
        "lng": 34.7807999
    },
    "publishedAddress": {
        "city": "Tel Aviv-Yafo",
        "country": "Israel",
        "full": "Shlomo Ibn Gabirol St 69, Tel Aviv-Yafo, Israel",
        "lat": 32.0817299,
        "lng": 34.7807999,
        "state": "Tel Aviv District",
        "zipcode": "6416201",
        "street": "Shlomo Ibn Gabirol Street 69"
    },
    "timezone": "Asia/Jerusalem",
    "_id": "<listingId>"
}

Best Practices

Before creating the listing, use the Google Maps API to determine the exact coordinates. Use the geocoding and reverse-geocoding features to ensure accuracy.
Enter the street name and number with the same format as Google Maps API.
Use 6-digit numbers for latitude and longitude.

🚧
Zipcode Requirement
Some booking channels require that all properties have a zipcode in their address. If your property legitimately doesn't have one, enter 0000as its value.

Cleaning Instructions

You can upload cleaning instructions for your guests that can be inserted into auto-messages when you include the {{listing_cleaning_instructions}} variable.

Available Endpoints

Method	Endpoint
PUT	/listing/{id}

Key Parameters

Path Parameter	Type	Description	Required
`id`	string	The property ID.	✔️

Body Parameter	Type	Description	Required
`cleaning`	object
`instructions`	string	Stores cleaning instructions for the property.

Request Example

curl --globoff --request PUT 'https://open-api.guesty.com/v1/listings/{id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--data '{
     "cleaning": {
        "instructions": "Cleaning instructions."
    }
}'

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", "Bearer {accessToken}");

const raw = JSON.stringify({
  "cleaning": {
    "instructions": "Cleaning instructions."
  }
});

const requestOptions = {
  method: "PUT",
  headers: myHeaders,
  body: raw,
  redirect: "manual"
};

fetch("https://open-api.guesty.com/v1/listings/{id}", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'PUT',
  'hostname': 'open-api.guesty.com',
  'path': '/v1/listings/{id}',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {accessToken}'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

var postData = JSON.stringify({
  "cleaning": {
    "instructions": "Cleaning instructions."
  }
});

req.write(postData);

req.end();

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://open-api.guesty.com/v1/listings/{id}',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => false,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_POSTFIELDS =>'{
     "cleaning": {
        "instructions": "Cleaning instructions."
    }
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer {accessToken}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import http.client
import json

conn = http.client.HTTPSConnection("open-api.guesty.com")
payload = json.dumps({
  "cleaning": {
    "instructions": "Cleaning instructions."
  }
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {accessToken}'
}
conn.request("PUT", "/v1/listings/{id}", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Guest Should Know

This is where you can store other useful information to share with your guests. These have related variables that can be used to populate the information in your auto-messages.

Available Endpoints

Method	Endpoint
PUT	/listing/{id}

Key Parameters

Path Parameter	Type	Description	Required
`id`	string	The property ID.	✔️

Body Parameter	Type	Description
`hostName`	string	The name of the host. E.g., `"Jeffrey"`.
`houseManual`	string	Provide a guide or instructions on how to use and care for the property during the guest's stay.
`parkingInstructions`	string	Information on parking facilities.
`trashCollectedOn`	string	Store instructions for trash disposal and collection days.
`wifiName`	string	For storing the wifi network name (SSID).
`wifiPassword`	string	For storing the wifi network password.

Request Example

curl --globoff --request PUT 'https://open-api.guesty.com/v1/listings/{id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--data '{
    "hostName": "string",
    "houseManual": "string",
    "parkingInstructions": "string",
    "trashCollectedOn": "string",
    "wifiName": "string",
    "wifiPassword": "string"
}'

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", "Bearer {accessToken}");

const raw = JSON.stringify({
  "hostName": "string",
  "houseManual": "string",
  "parkingInstructions": "string",
  "trashCollectedOn": "string",
  "wifiName": "string",
  "wifiPassword": "string"
});

const requestOptions = {
  method: "PUT",
  headers: myHeaders,
  body: raw,
  redirect: "manual"
};

fetch("https://open-api.guesty.com/v1/listings/{id}", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'PUT',
  'hostname': 'open-api.guesty.com',
  'path': '/v1/listings/{id}',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {accessToken}'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

var postData = JSON.stringify({
  "hostName": "string",
  "houseManual": "string",
  "parkingInstructions": "string",
  "trashCollectedOn": "string",
  "wifiName": "string",
  "wifiPassword": "string"
});

req.write(postData);

req.end();

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://open-api.guesty.com/v1/listings/{id}',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => false,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_POSTFIELDS =>'{
    "hostName": "string",
    "houseManual": "string",
    "parkingInstructions": "string",
    "trashCollectedOn": "string",
    "wifiName": "string",
    "wifiPassword": "string"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer {accessToken}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import http.client
import json

conn = http.client.HTTPSConnection("open-api.guesty.com")
payload = json.dumps({
  "hostName": "string",
  "houseManual": "string",
  "parkingInstructions": "string",
  "trashCollectedOn": "string",
  "wifiName": "string",
  "wifiPassword": "string"
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {accessToken}'
}
conn.request("PUT", "/v1/listings/{id}", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Property Location & Details

Overview

🚧
Address Change Notice

Retrieving the Property's Address

Available Endpoints

Key Parameters

Example

Editing the Property Address

📘
Differentiating Between Address Objects

Available Endpoints

Key Parameters

Example

Best Practices

🚧
Zipcode Requirement

Cleaning Instructions

Available Endpoints

Key Parameters

Request Example

Guest Should Know

Available Endpoints

Key Parameters

Request Example

Overview

🚧Address Change Notice

Retrieving the Property's Address

Available Endpoints

Key Parameters

Example

Editing the Property Address

📘Differentiating Between Address Objects

Available Endpoints

Key Parameters

Example

Best Practices

🚧Zipcode Requirement

Cleaning Instructions

Available Endpoints

Key Parameters

Request Example

Guest Should Know

Available Endpoints

Key Parameters

Request Example

🚧
Address Change Notice

📘
Differentiating Between Address Objects

🚧
Zipcode Requirement