Listings APIListings API
Get API keySign in

Photos

Add, list, remove, and star location photos via client.photos.

All photo methods live under client.photos. Every method takes a location_id except upload_status, and location_id accepts numeric or base64-encoded IDs, see Location IDs.

Photos are attached by public URL rather than uploaded as multipart form data: you host the image, the platform fetches it, and processing continues in the background. Photo types are LOGO, COVER, and ADDITIONAL.

photos.list

Get the media files attached to a location, starred and unstarred.

Python
client.photos.list(location_id: str | int) -> list[APIObject]
Python
photos = client.photos.list(16808)for photo in photos:  print(photo.id, photo.categoryName, photo.starred)

Returns the mediaFilesOfLocation list. Each item has id, url, thumbnailUrl, categoryName, categoryId, fileType, starred, and viewsCount. The id is what you pass to remove and star. See Get photos for a location.

photos.add

Attach one or more photos to a location. Each item in photos needs a photo key holding a public image URL and a type key.

Python
client.photos.add(    location_id: str | int,    photos: list[dict[str, Any]],) -> APIObject
KeyTypeDescription
photostrPublic URL of the image to fetch.
typestrLOGO, COVER, or ADDITIONAL.
Python
result = client.photos.add(16808, [  {"photo": "https://cdn.example.com/acme-logo.png", "type": "LOGO"},  {"photo": "https://cdn.example.com/acme-storefront.jpg", "type": "ADDITIONAL"},])for photo in result.photos:  print(photo.id, photo.type)

Returns the addLocationPhotos object with success, photos, request, and errors. Each entry in photos carries id, databaseId, url, thumbnailUrl, type, and starred. See Upload photos to a location.

photos.remove

Detach photos from a location by their media IDs.

Python
client.photos.remove(    location_id: str | int,    photo_ids: list[str],) -> APIObject
Python
result = client.photos.remove(16808, ["TWVkaWFGaWxlOjU4Nzg5MzE="])print(result.removedCount)

Returns the removeLocationPhotos object with removedCount and errors. See Remove photos from a location.

photos.star

Star or unstar photos so supported publishers place them first. Pass starred=False to unstar. A maximum of 4 photos can be starred per account.

Python
client.photos.star(    location_id: str | int,    media_ids: list[str],    *,    starred: bool = True,) -> APIObject

The Python parameter is named media_ids, and it holds the same media id values that photos.list returns. The SDK sends them as the photoIds field on the wire, so you never build that field yourself.

Python
# Star two photosclient.photos.star(16808, ["TWVkaWFGaWxlOjU4Nzg5MzI=", "TWVkaWFGaWxlOjU4Nzg5MzM="]) # Unstar oneresult = client.photos.star(16808, ["TWVkaWFGaWxlOjU4Nzg5MzI="], starred=False)for photo in result.photos:  print(photo.id, photo.starred)

Returns the starUnstarLocationPhotos object with success, photos, and error. See Star location photos.

photos.upload_status

Check how a bulk photo upload is progressing. Poll this when you added many photos at once and need per-image results.

Python
client.photos.upload_status(request_id: str) -> APIObject
Python
status = client.photos.upload_status("e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a")print(status.to_dict())

See Check bulk photo upload status for the per-photo status and error fields, including the rejection reasons a photo can come back with.

See also

  • Upload location photos: the end-to-end photo guide, including size limits
  • Locations: create and update the locations you attach photos to
  • Posts: attach a single image to a post with media_url