Property Location & Details

Retrieve an existing listing's address or update a listing's address and related 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

Key Parameters

Path ParameterTypeDescriptionRequired
idstringThe property ID.✔️
Query ParameterTypeDescriptionRequired
fieldsstringSpecify 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

MethodEndpoint
PUT/listing/{id}

Key Parameters

Path ParameterTypeDescriptionRequired
idstringThe property's ID✔️
Body ParameterTypeDescriptionRequired
addressobjectThe property's precise street address. See the following table.✔️
publishedAddressobjectThe property's general street address. See the table below.

Address Object

Path ParameterTypeDescriptionRequired
fullstringThe complete street address.
streetstringStreet name and number.✔️
aptstringApartment or unit number.
citystringName of the city within which the property is located.✔️
statestringThe state or area within which the city is located.✔️
countrystringName of the country.✔️
zipcodestringThe zip or postal code of the street address.✔️
latstringThe latitude coordinates of the location in decimal format.✔️
lngstringThe longitude coordinates of the location in decimal format.✔️

Published Address Object

Path ParameterTypeDescriptionRequired
streetstringStreet name and number.✔️
aptstringApartment or unit number.
citystringName of the city within which the property is located.
statestringThe state or area within which the city is located.
countrystringName of the country.✔️
zipcodestringThe zip or postal code of the street address.✔️
latstringThe latitude coordinates of the location in decimal format.✔️
lngstringThe longitude coordinates of the location in decimal format.✔️
fullstringThe 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

MethodEndpoint
PUT/listing/{id}

Key Parameters

Path ParameterTypeDescriptionRequired
idstringThe property ID.✔️
Body ParameterTypeDescriptionRequired
cleaningobject
  instructionsstringStores 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

MethodEndpoint
PUT/listing/{id}

Key Parameters

Path ParameterTypeDescriptionRequired
idstringThe property ID.✔️
Body ParameterTypeDescriptionRequired
hostNamestringThe name of the host. E.g., "Jeffrey".
houseManualstringProvide a guide or instructions on how to use and care for the property during the guest's stay.
parkingInstructionsstringInformation on parking facilities.
trashCollectedOnstringStore instructions for trash disposal and collection days.
wifiNamestringFor storing the wifi network name (SSID).
wifiPasswordstringFor 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"))