Photos
Working with photos reflects various systems, so the ways of working with them are very flexible.
You can send photos in the formats JPEG, PNG, GIF, BMP, TIFF and WebP (processing is described in the agenda photo)
At the ad level
If you send the photos structure at the ad level, the photos are processed automatically so that the ad's photos are updated to contain only the photos in this structure (old ones are deleted, new ones added).
Photo updates can be controlled with the stamp parameter - you provide your own parameter, and when it changes, the photo is updated even if the URL is the same. If the URL also changes when a photo changes, you do not need to use stamp – but a new URL is a new photo that is added at the end of the gallery (replacing the main photo is an exception, see Order and main photo); a change of stamp replaces the photo in the same place. If you do use it, we recommend using e.g. the datetime, file size, file hash etc.
At the ad level, there are also three possible attributes for photos:
ignoreimport="true"- thephotosstructure is ignoredforceupdate="true"- forces an update of all photos regardless of any change of URL orstamp(all photos get new IDs, see below)reorder="true"- the gallery is sorted by the order of the photos inphotos(see Order and main photo)
Using the agenda photo
Using the agenda photo you can add/update/delete photos, always one photo at a time.
Specifying the photo ID for an ad is not required - but read the behaviour of the individual options.
1. Adding/updating photos using url
If you specify the element url, the behaviour is as follows:
- If the photo ID is specified, it is checked whether this photo has the same
urlandstamp, and if needed only that photo is updated. - If the photo ID is not specified, it is checked whether the same
urlexists for this ad, and if needed this image is updated according tostamporforceupdate. If the address is not found, a new image is created
2. Adding/updating photos using content
If you specify the element content, the behaviour is as follows:
- If the photo ID is specified, the photo is always overwritten with the content given in
content - If the photo ID is not specified, a new image is always created
3. Adding/updating photos using raw-data
Instead of the XML structure, you can send the JPG data directly in a PUT request, but you must specify the URL parameter ?raw-data=true
- If the photo ID is specified, the photo is always overwritten with the RAW-DATA content
- If the photo ID is not specified, a new image is always created
Recommendation: Since whether a photo is created or added depends on the context of the data, the Location: header is not returned; instead, a structure is always returned containing the ID of the photo that was updated/inserted.
Deleting a photo
Possible either by sending the HTTP method DELETE or by sending a PUT/POST method with the element <photo action="delete">
Order and main photo
The order of the photos in the gallery and the main photo (the one shown in the ad overview) are one mechanism: the main photo is always at position 1.
The same rules apply to all paths – the ad import with the photos structure, the agenda photo and the sub-agenda photo/sort.
When reading, the position of the photo is in the element sortOrder (1 = main photo), in the same order in which the website shows the photos.
Values of main (the same everywhere): 1 or true = main photo, 0 or false = not the main photo, empty value = not set.
We recommend lower case. Any other value is ignored and the response contains a warning.
In the ad import (photos), the order changes only when you explicitly ask for it:
| What you send | What happens |
|---|---|
only the list of photos, without main = 1, sortOrder and reorder |
neither the order nor the main photo changes; new photos are added at the end, photos previously imported via the API that are missing from the list are deleted and the others move up |
| the same, but the ad has no photos yet | the order is taken from photos, the first photo is the main one |
main = 1 for a photo |
the photo becomes the main photo and moves to position 1, the other photos keep their relative order; if several photos have main = 1, the first of them applies |
main = 0 without sortOrder |
on its own it changes nothing – you can choose a different main photo only by marking it with main = 1 |
sortOrder for a photo |
the photo is placed at the given position (absolute position, see below) |
<photos reorder="true"> |
the gallery is sorted by the order of the photos in photos; photos that are not there (e.g. uploaded in the administration) are placed after them in their existing order; main and sortOrder apply here too |
the import deletes the current main photo (it is no longer in photos) and specifies neither the main photo nor the order (no main = 1, sortOrder or reorder) |
the first newly added photo becomes the main photo and gets position 1 – so the title photo can also be replaced with a new URL; if no new photo was added, the next photo in the existing order becomes the main one |
sortOrder is an absolute position. The photo is placed at the given position and the other photos fill the remaining positions – without reorder in their existing order, with reorder="true" in the order from photos.
A number greater than the number of photos means the end of the gallery. If several photos ask for the same position, the first of them gets it and the others go to the nearest free positions after it.
Example: gallery A, B, C, D and you send sortOrder = 2 for photo C → result A, C, B, D.
sortOrder = 1 makes the photo the main photo. sortOrder other than 1 together with main = 1, or 1 together with main = 0, is an error and the request is not processed.
Replacing a photo and its ID
- Replacement via
stampin the ad import (the same URL and a differentstamp, orforceupdate="true"): the photo is downloaded again and gets a new ID (and thus a new address on our side); its position in the gallery and whether it is the main photo stay the same. If the download fails, the original photo stays and the import tries the replacement again next time. - Replacement with a new URL in the ad import: for the API this is a new photo – the old one is deleted and the new one is added at the end of the gallery (for the exception for the main photo, see the table above). To replace a photo in the same place, keep the URL and change
stamp. - Replacement via
PUT /photo/{id}(agendaphoto): the content is overwritten under the same ID; its position in the gallery and whether it is the main photo stay the same. - After every addition or deletion of a photo by any path, the order is normalised: positions always run continuously from 1 and there is exactly one main photo. The relative order of the photos does not change.
Be careful with forceupdate="true": it downloads all photos of the ad again and gives all of them new IDs and new URLs. Send it only in exceptional cases (e.g. when changing systems), not with every import.
To change the order of several photos at once without sending the whole ad, use the sub-agenda photo/sort; to change the position or the main photo of one photo, use PUT /photo/{id} with sortOrder or main.
