{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Location Photo Management – API Consumer Guide","description":"Explore the Uberall API to integrate powerful local marketing, reputation management, and business listing solutions into your applications.","keywords":"uberall, api, local marketing, reputation management, business listings, location data, online presence, reviews, local search","lang":"en-US","image":"/assets/logo.7debf27ce4b0f61bb0a268e1ac309f05d031cfa02db9baf02842030a31a09baa.cdc3be38.svg","siteUrl":"https://docs.uberall.com","jsonLd":{"@context":"https://schema.org","@type":"Organization","url":"https://uberall.com","name":"Uberall","contactPoint":{"@type":"ContactPoint","telephone":"+49 (0)30 208 479 320","contactType":"Customer service","email":"api@uberall.com"}},"meta":[{"name":"twitter:card","content":"summary_large_image"},{"name":"twitter:title","content":"Uberall API Documentation"},{"name":"twitter:description","content":"Build powerful local marketing solutions with the Uberall API"},{"name":"twitter:image","content":"/assets/logo.7debf27ce4b0f61bb0a268e1ac309f05d031cfa02db9baf02842030a31a09baa.cdc3be38.svg"}],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"location-photo-management--api-consumer-guide","__idx":0},"children":["Location Photo Management – API Consumer Guide"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide explains how to manage photos on a location and when to use each endpoint."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["two supported workflows"]},":"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Single-photo operations"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/photos"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Full photo-set management (bulk)"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/locations/$id"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Understanding the difference is critical."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"1-single-photo-workflow--apiphotos-","__idx":1},"children":["1. Single Photo Workflow (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/photos"]},")"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this when you want to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Upload ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["one image file"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Update metadata of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["one existing photo"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Delete a specific photo"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"upload-one-photo","__idx":2},"children":["Upload one photo"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/photos"]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Important"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Only one photo per request"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["This endpoint does not support URL or base64 uploads"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Crop fields must be sent all together or not at all"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identifier"]}," must be unique per location"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"update-metadata-only","__idx":3},"children":["Update metadata only"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH /api/photos/$id"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Content-Type:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can update:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identifier"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["crop values"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You cannot replace the image file here."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"delete-a-photo","__idx":4},"children":["Delete a photo"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /api/photos/$id"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Removes the photo permanently."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"2-bulk-photo-management--patch-apilocationsid-","__idx":5},"children":["2. Bulk Photo Management (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH /api/locations/$id"]},")"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this when you want to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add multiple photos at once"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Upload by URL"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Upload by base64"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reorder photos"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Replace the entire photo set in one request"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"critical-behavior-replace-all-semantics","__idx":6},"children":["Critical Behavior: Replace-All Semantics"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Warning:"]}," Due to the default behavior of the endpoint, if your request body includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["photos"]}," array:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The location's entire photo set will match ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["exactly"]}," what you send."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Any existing photo ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not included will be deleted"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If you ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["omit"]}," the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["photos"]}," attribute from the request, existing photos remain unchanged."]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"supported-formats-inside-photos","__idx":7},"children":["Supported formats inside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["photos"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You must identify each photo in one of these ways:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"1-keep-existing-photo","__idx":8},"children":["1. Keep existing photo"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{ \"id\": 98765 }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"2-keep-existing-photo-by-identifier","__idx":9},"children":["2. Keep existing photo by identifier"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{ \"identifier\": \"external-123\" }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"3-create-new-photo-from-url","__idx":10},"children":["3. Create new photo from URL"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"url\": \"https://example.com/store.jpg\",\n  \"type\": \"MAIN\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"4-create-new-photo-from-base64","__idx":11},"children":["4. Create new photo from base64"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"photo\": \"data:image/jpeg;base64,...\",\n  \"type\": \"PHOTO\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"bulk-example","__idx":12},"children":["Bulk Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X PATCH https://<base>/api/locations/4207896 \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-KEY: YOUR_KEY\" \\\n  -d '{\n    \"photos\": [\n      {\n        \"url\": \"https://example.com/storefront.jpg\",\n        \"type\": \"MAIN\",\n        \"order\": 0\n      },\n      {\n        \"url\": \"https://example.com/interior.jpg\",\n        \"type\": \"PHOTO\",\n        \"order\": 1\n      },\n      {\n        \"id\": 98765,\n        \"description\": \"Updated caption\"\n      }\n    ]\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Result:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The location will have exactly these three photos"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In the order specified"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Any other previous photos are removed"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"photo-types-important-rules","__idx":13},"children":["Photo Types (Important Rules)"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MAIN"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Always allowed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PHOTO"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Default general type"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Other types"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Most allow only one per location"]}]}]}]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Type availability depends on business category and connected directories"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Some types (Google-specific) are category-restricted"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To retrieve file size, dimension, and type constraints:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /api/rules-engine/all-photo-constraints\n"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-mistakes","__idx":14},"children":["Common Mistakes"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sending JSON to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/photos"]}," instead of multipart"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Including ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["photos"]}," in location PATCH without listing all existing photos"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sending crop fields partially"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reusing the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identifier"]}," on the same location"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Uploading a second single-slot type (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INTERIOR"]},")"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"decision-guide","__idx":15},"children":["Decision Guide"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Situation"},"children":["Situation"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Use"},"children":["Use"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["I have a single image file"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/photos"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["I need to update one photo's caption/type"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH /api/photos/$id"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["I want to upload multiple images"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH /api/locations/$id"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["I want to upload by URL"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH /api/locations/$id"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["I want to reorder photos"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH /api/locations/$id"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["I want to fully control the photo set"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH /api/locations/$id"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"final-recommendation","__idx":16},"children":["Final Recommendation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you are synchronizing photos from an external system, always use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH /api/locations/$id"]}," with the full ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["photos"]}," array to keep both systems in sync safely and predictably."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/photos"]}," only for manual or one-off operations."]}]},"headings":[{"value":"Location Photo Management – API Consumer Guide","id":"location-photo-management--api-consumer-guide","depth":1},{"value":"1. Single Photo Workflow ( /api/photos )","id":"1-single-photo-workflow--apiphotos-","depth":2},{"value":"Upload one photo","id":"upload-one-photo","depth":3},{"value":"Update metadata only","id":"update-metadata-only","depth":3},{"value":"Delete a photo","id":"delete-a-photo","depth":3},{"value":"2. Bulk Photo Management ( PATCH /api/locations/$id )","id":"2-bulk-photo-management--patch-apilocationsid-","depth":2},{"value":"Critical Behavior: Replace-All Semantics","id":"critical-behavior-replace-all-semantics","depth":3},{"value":"Supported formats inside photos","id":"supported-formats-inside-photos","depth":3},{"value":"1. Keep existing photo","id":"1-keep-existing-photo","depth":4},{"value":"2. Keep existing photo by identifier","id":"2-keep-existing-photo-by-identifier","depth":4},{"value":"3. Create new photo from URL","id":"3-create-new-photo-from-url","depth":4},{"value":"4. Create new photo from base64","id":"4-create-new-photo-from-base64","depth":4},{"value":"Bulk Example","id":"bulk-example","depth":3},{"value":"Photo Types (Important Rules)","id":"photo-types-important-rules","depth":2},{"value":"Common Mistakes","id":"common-mistakes","depth":2},{"value":"Decision Guide","id":"decision-guide","depth":2},{"value":"Final Recommendation","id":"final-recommendation","depth":2}],"frontmatter":{"seo":{"title":"Location Photo Management – API Consumer Guide"}},"lastModified":"2026-03-09T09:58:52.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/location-photo-management","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}