Téléverser un logo, une image de couverture et des photos

Ajoutez par URL logo, couverture et photos de galerie à un établissement, listez les médias, étoilez l’image principale et supprimez les médias obsolètes.

Les photos sont associées à un établissement par URL publique : vous hébergez l'image, l'API la récupère et la stocke, puis les plateformes de publication la récupèrent depuis cet emplacement. Un établissement conserve un logo, une image de couverture et un nombre quelconque de photos supplémentaires, dont 4 au maximum peuvent être marquées d'une étoile pour bénéficier d'un affichage prioritaire.

1. Téléverser par URL

POST /locations/photos accepte input.locationId et un tableau input.photos. L'URL de chaque élément doit figurer dans un champ nommé photo, et non url. Définissez explicitement type sur LOGO, COVER ou ADDITIONAL ; un élément sans type est stocké comme photo supplémentaire.

curl -X POST https://listingsapi.com/api/v4/locations/photos \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photos": [      { "photo": "https://cdn.example.com/jenny-home/logo.png", "type": "LOGO" },      { "photo": "https://cdn.example.com/jenny-home/cover.jpg", "type": "COVER" },      { "photo": "https://cdn.example.com/jenny-home/storefront.jpg", "type": "ADDITIONAL" }    ]  }}'

{  "data": {    "addLocationPhotos": {      "success": true,      "request": {},      "photos": [        { "id": "TWVkaWFGaWxlOjU4Nzg5MzE=", "databaseId": 5878931, "type": "LOGO", "starred": false,          "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/f47d62a6.png" },        { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "databaseId": 5878932, "type": "ADDITIONAL", "starred": false }      ],      "errors": null    }  }}

Conservez le id de chaque photo : c'est la valeur qu'acceptent les endpoints de marquage par étoile et de suppression. Téléverser à nouveau un LOGO ou un COVER remplace celui qui existe déjà. Un petit lot est stocké directement lors de l'appel, comme ici. Un lot volumineux est, lui, mis en file d'attente : photos est renvoyé vide et request.requestId est renseigné. Choisissez le traitement selon la présence de requestId, puis interrogez périodiquement GET /locations/photos/requests/{requestId}.

curl https://listingsapi.com/api/v4/locations/photos/requests/e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a \-H "Authorization: API $LISTINGSAPI_KEY"

2. Lister les médias associés

GET /locations/{locationId}/photos renvoie tous les fichiers multimédias de l'établissement sous la forme d'un simple tableau. Utilisez-le pour vérifier si un logo ou une image de couverture manque avant de téléverser des fichiers, et pour recueillir les identifiants nécessaires aux 2 étapes suivantes. Le chemin accepte l'identifiant encodé en base64 ou le nombre brut.

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/photos \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "mediaFilesOfLocation": [      { "id": "TWVkaWFGaWxlOjU4Nzg5MzE=", "categoryName": "Logo", "categoryId": "4", "starred": false, "viewsCount": 0 },      { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "categoryName": "Additional", "categoryId": "12", "starred": true, "viewsCount": 143 }    ]  }}

categoryName vaut Logo, Cover ou Additional. Un établissement sans médias renvoie un tableau vide, et non une erreur.

3. Marquer d'une étoile des photos supplémentaires

POST /locations/photos/star marque les photos supplémentaires pour leur accorder un affichage prioritaire sur les plateformes de publication qui prennent en charge la mise en avant d'images. Seules les photos ADDITIONAL peuvent être marquées d'une étoile, à raison de 4 au maximum par établissement ; une cinquième fait échouer l'ensemble de l'appel avec SY15012. Vous pouvez également transmettre starred: true sur un élément lors du téléversement.

curl -X POST https://listingsapi.com/api/v4/locations/photos/star \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photoIds": ["TWVkaWFGaWxlOjU4Nzg5MzI="],    "starred": true  }}'

{  "data": {    "starUnstarLocationPhotos": {      "success": true,      "photos": [        { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "type": "ADDITIONAL", "starred": true }      ],      "error": null    }  }}

La clé de réponse est starUnstarLocationPhotos et contient un seul error, et non un tableau errors. L'indicateur starred dans le corps contrôle l'action : envoyez false pour retirer l'étoile. Les méthodes du SDK acceptent le même booléen.

4. Supprimer une photo

POST /locations/photos/remove dissocie les photos supplémentaires à partir de leur identifiant. removedCount indique combien ont été dissociées ; ainsi, 0 avec errors: null signifie qu'aucun de ces identifiants n'était associé à cet établissement.

curl -X POST https://listingsapi.com/api/v4/locations/photos/remove \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photoIds": ["TWVkaWFGaWxlOjU4Nzg5MzI="]  }}'

{  "data": {    "removeLocationPhotos": {      "removedCount": 1,      "errors": null    }  }}

Seules les photos ADDITIONAL peuvent être supprimées ici. Pour changer le logo ou l'image de couverture, téléversez une nouvelle image avec ce type : elle remplace l'ancienne. La suppression dissocie le fichier de l'établissement ; elle ne le supprime pas nécessairement de votre médiathèque.

5. Utilisation de chaque emplacement par les plateformes de publication

Étapes suivantes

• Mettre à jour un établissement : horaires, fermetures et catégories Google dans le même enregistrement.
• Vérifier l’état des fiches et les liens actifs : consultez quand les plateformes de publication ont publié les nouvelles images.
• Importer des photos, Récupérer des photos, Marquer des photos comme favorites, Supprimer des photos et État de l’importation en masse : les pages de référence.
• Références des SDK : Photos avec Python et Photos avec Node.