Property Photos

The advantages of listing photos and how to use the API to manage them.

Suggest Edits

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

MethodEndpoint
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

MethodEndpoint
PUT/listings/{id}

Key Parameters

Path ParameterTypeDescriptionRequired
idstringThe property ID.✔️
Body ParameterTypeDescriptionRequired
pictures[object]The property object. See the next section for a breakdown.✔️

The Picture Object

Body ParameterTypeDescriptionRequired
originalstringURL of the original uploaded image.✔️
thumbnailstringURL of the thumbnail-sized version of the image. The recommended height for the image is 200 pixels. Guesty will scale the width proportionally.✔️
captionstringUse 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.

Updated 11 days ago