Location Photo Management – API Consumer Guide

This guide explains how to manage photos on a location and when to use each endpoint.

There are two supported workflows:

1. Single-photo operations → /api/photos
2. Full photo-set management (bulk) → /api/locations/$id

Understanding the difference is critical.

Use this when you want to:

• Upload one image file
• Update metadata of one existing photo
• Delete a specific photo

POST /api/photos

Important

• Only one photo per request
• This endpoint does not support URL or base64 uploads
• Crop fields must be sent all together or not at all
• identifier must be unique per location

PATCH /api/photos/$id
Content-Type: application/json

You can update:

• type
• description
• identifier
• crop values

You cannot replace the image file here.

DELETE /api/photos/$id

Removes the photo permanently.

Use this when you want to:

• Add multiple photos at once
• Upload by URL
• Upload by base64
• Reorder photos
• Replace the entire photo set in one request

Warning: Due to the default behavior of the endpoint, if your request body includes a photos array:

• The location's entire photo set will match exactly what you send.
• Any existing photo not included will be deleted.
• If you omit the photos attribute from the request, existing photos remain unchanged.

You must identify each photo in one of these ways:

{ "id": 98765 }

{ "identifier": "external-123" }

{
  "url": "https://example.com/store.jpg",
  "type": "MAIN"
}

{
  "photo": "data:image/jpeg;base64,...",
  "type": "PHOTO"
}

curl -X PATCH https://<base>/api/locations/4207896 \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_KEY" \
  -d '{
    "photos": [
      {
        "url": "https://example.com/storefront.jpg",
        "type": "MAIN",
        "order": 0
      },
      {
        "url": "https://example.com/interior.jpg",
        "type": "PHOTO",
        "order": 1
      },
      {
        "id": 98765,
        "description": "Updated caption"
      }
    ]
  }'

Result:

• The location will have exactly these three photos
• In the order specified
• Any other previous photos are removed

• Type availability depends on business category and connected directories
• Some types (Google-specific) are category-restricted

To retrieve file size, dimension, and type constraints:

GET /api/rules-engine/all-photo-constraints

• Sending JSON to /api/photos instead of multipart
• Including photos in location PATCH without listing all existing photos
• Sending crop fields partially
• Reusing the same identifier on the same location
• Uploading a second single-slot type (e.g., INTERIOR)

If you are synchronizing photos from an external system, always use PATCH /api/locations/$id with the full photos array to keep both systems in sync safely and predictably.

Use /api/photos only for manual or one-off operations.