# 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.

## 1. Single Photo Workflow (`/api/photos`)

Use this when you want to:

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


### Upload one 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



### Update metadata only

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

You can update:

- `type`
- `description`
- `identifier`
- crop values


You cannot replace the image file here.

### Delete a photo

`DELETE /api/photos/$id`

Removes the photo permanently.

## 2. Bulk Photo Management (`PATCH /api/locations/$id`)

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


### Critical Behavior: Replace-All Semantics

> **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.



### Supported formats inside `photos`

You must identify each photo in one of these ways:

#### 1. Keep existing photo


```json
{ "id": 98765 }
```

#### 2. Keep existing photo by identifier


```json
{ "identifier": "external-123" }
```

#### 3. Create new photo from URL


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

#### 4. Create new photo from base64


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

### Bulk Example


```bash
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


## Photo Types (Important Rules)

| Type | Notes |
|  --- | --- |
| `MAIN` | Always allowed |
| `PHOTO` | Default general type |
| Other types | Most allow only one per location |


- 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
```

## Common Mistakes

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


## Decision Guide

| Situation | Use |
|  --- | --- |
| I have a single image file | `POST /api/photos` |
| I need to update one photo's caption/type | `PATCH /api/photos/$id` |
| I want to upload multiple images | `PATCH /api/locations/$id` |
| I want to upload by URL | `PATCH /api/locations/$id` |
| I want to reorder photos | `PATCH /api/locations/$id` |
| I want to fully control the photo set | `PATCH /api/locations/$id` |


## Final Recommendation

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.