Property Photos

Overview

Including photos in listings can make them more eye-catching in search results. Hosts can use photos to give potential guests a glimpse of what they can expect from their place's inside, outside, and surrounding area. The listings API allows you to access one or multiple photos, add new photos, and edit or remove existing ones.

For Guesty's recommendations and requirements, click here.

Retrieve Pictures

Available Endpoints

Method	Endpoint
GET	/listings/{id}
GET	/listings

Request Example

curl 'https://open-api.guesty.com/v1/listings/{id}?fields=pictures' \
--header 'Authorization: Bearer {accessToken}'

const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {accessToken}");

const requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "manual"
};

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

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://open-api.guesty.com/v1/listings/{id}?fields=pictures',
  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',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer {accessToken}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import http.client

conn = http.client.HTTPSConnection("open-api.guesty.com")
payload = ''
headers = {
  'Authorization': 'Bearer {accessToken}'
}
conn.request("GET", "/v1/listings/66054019764cbb000f37c450?fields=pictures", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Response Example

{
    "_id": "<listingId>",
    "type": "<string>",
    "tags": [
        "<tag>"
    ],
    "pictures": [
        {
            "_id": "<pictureId>",
            "original": "<URL>",
            "thumbnail": "<URL>",
            "height": 1280,
            "width": 1920,
            "size": 180129,
            "caption": "<string>"
        },
        {
            "_id": "<pictureId>",
            "original": "<URL>",
            "thumbnail": "<URL>",
            "height": 1280,
            "width": 1920,
            "size": 180129,
            "caption": "<string>"
        },
        {
            "_id": "<pictureId>",
            "original": "<URL>",
            "thumbnail": "<URL>",
            "height": 1280,
            "width": 1920,
            "size": 180129,
            "caption": "<string>"
        }
    ]
    "accountId": "<accountId>"
}

Adding a Picture

Available Endpoints

Method	Endpoint
PUT	/listings/{id}

Key Parameters

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

Body Parameter	Type	Description	Required
`pictures`	[object]	The property object. See the next section for a breakdown.	✔️

The Picture Object

Body Parameter	Type	Description	Required
`original`	string	URL of the original uploaded image.	✔️
`thumbnail`	string	URL of the thumbnail-sized version of the image. The recommended height for the image is 200 pixels. Guesty will scale the width proportionally.	✔️
`caption`	string	Use this to enter a text description explaining the image.	Recommended

To add a picture to an existing array, insert the new picture object into the array.

Example

curl --request PUT 'https://open-api.guesty.com/v1/listings/{id}?fields=pictures' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--data '{
    "pictures": [
        {
            "_id": "<pictureId>",
            "original": "<URL>",
            "thumbnail": "<URL>",
            "height": 1280,
            "width": 1920,
            "size": 180129,
            "caption": "<string>"
        },
        {
            "_id": "<pictureId>",
            "original": "<URL>",
            "thumbnail": "<URL>",
            "height": 1280,
            "width": 1920,
            "size": 180129,
            "caption": "<string>"
        },
        {
            "_id": "<pictureId>",
            "original": "<URL>",
            "thumbnail": "<URL>",
            "height": 1280,
            "width": 1920,
            "size": 180129,
            "caption": "<string>"
        },
        {
            "original": "<URL>",
            "thumbnail": "<URL>",
            "caption": "<string>"
        }
    ]
}'

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

const raw = JSON.stringify({
  "pictures": [
    {
      "_id": "<pictureId>",
      "original": "<URL>",
      "thumbnail": "<URL>",
      "height": 1280,
      "width": 1920,
      "size": 180129,
      "caption": "<string>"
    },
    {
      "_id": "<pictureId>",
      "original": "<URL>",
      "thumbnail": "<URL>",
      "height": 1280,
      "width": 1920,
      "size": 180129,
      "caption": "<string>"
    },
    {
      "_id": "<pictureId>",
      "original": "<URL>",
      "thumbnail": "<URL>",
      "height": 1280,
      "width": 1920,
      "size": 180129,
      "caption": "<string>"
    },
    {
      "original": "<URL>",
      "thumbnail": "<URL>",
      "caption": "<string>"
    }
  ]
});

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

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

<?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 =>'{
    "pictures": [
        {
            "_id": "<pictureId>",
            "original": "<URL>",
            "thumbnail": "<URL>",
            "height": 1280,
            "width": 1920,
            "size": 180129,
            "caption": "<string>"
        },
        {
            "_id": "<pictureId>",
            "original": "<URL>",
            "thumbnail": "<URL>",
            "height": 1280,
            "width": 1920,
            "size": 180129,
            "caption": "<string>"
        },
        {
            "_id": "<pictureId>",
            "original": "<URL>",
            "thumbnail": "<URL>",
            "height": 1280,
            "width": 1920,
            "size": 180129,
            "caption": "<string>"
        },
        {
            "original": "<URL>",
            "thumbnail": "<URL>",
            "caption": "<string>"
        }
    ]
}',
  CURLOPT_HTTPHEADER => array(
    'accept: application/json',
    '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({
  "pictures": [
    {
      "_id": "<pictureId>",
      "original": "<URL>",
      "thumbnail": "<URL>",
      "height": 1280,
      "width": 1920,
      "size": 180129,
      "caption": "<string>"
    },
    {
      "_id": "<pictureId>",
      "original": "<URL>",
      "thumbnail": "<URL>",
      "height": 1280,
      "width": 1920,
      "size": 180129,
      "caption": "<string>"
    },
    {
      "_id": "<pictureId>",
      "original": "<URL>",
      "thumbnail": "<URL>",
      "height": 1280,
      "width": 1920,
      "size": 180129,
      "caption": "<string>"
    },
    {
      "original": "<URL>",
      "thumbnail": "<URL>",
      "caption": "<string>"
    }
  ]
})
headers = {
  'accept': 'application/json',
  '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"))

Remove a Picture

To remove a picture from the property, remove the relevant object from the pictures array. To erase all pictures, push an empty pictures array.

curl --request PUT 'https://open-api.guesty.com/v1/listings/64f03f9094d741004fda977d' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--data '{
    "pictures": []
}'

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

const raw = JSON.stringify({
  "pictures": []
});

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));

<?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 =>'{
    "pictures": []
}',
  CURLOPT_HTTPHEADER => array(
    'accept: application/json',
    '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({
  "pictures": []
})
headers = {
  'accept': 'application/json',
  '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"))

You can then create a new array with the relevant information.

curl --request PUT 'https://open-api.guesty.com/v1/listings/64f03f9094d741004fda977d' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--data '{
    "pictures": [
        {
            "original": "<URL>",
            "thumbnail": "<URL>",
            "caption": "<string>"
        }
    ]
}'

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

const raw = JSON.stringify({
  "pictures": [
    {
      "original": "<URL>",
      "thumbnail": "<URL>",
      "caption": "<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));

<?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 =>'{
    "pictures": [
        {
            "original": "<URL>",
            "thumbnail": "<URL>",
            "caption": "<string>"
        }
    ]
}',
  CURLOPT_HTTPHEADER => array(
    'accept: application/json',
    '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({
  "pictures": [
    {
      "original": "<URL>",
      "thumbnail": "<URL>",
      "caption": "<string>"
    }
  ]
})
headers = {
  'accept': 'application/json',
  '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"))

Picture Order

Pictures are ordered according to their place in the array. To change the position of a picture, move its object to the correct position in the array.

📘
Repository Consolidation
Contact Customer Experience if you wish to migrate to and consolidate your property photos on Guesty's storage repository.

Room Photos (Beta)

You can assign pictures to a specific room. To learn more, refer to Assign a Photo to a Space.

Overview

Retrieve Pictures

Available Endpoints

Request Example

Response Example

Adding a Picture

Available Endpoints

Key Parameters

Example

Remove a Picture

Picture Order

📘Repository Consolidation

Room Photos (Beta)

📘
Repository Consolidation