PIWIGO WS API - pwg.categories.getImages - categories field always contains just one category #727

New Issue

2026-10-05T00:14:07+02:00

adam commented

2026-10-05 00:14:07 +02:00

When you call pwg.categories.getImages for a category, all resources are returned with just a single category in their list of categories. This is regardless of how many they are linked to.
This is an issue if you then wish to unlink a resource(s) (e.g. image), because you do not know whether it will result in an orphan unless you first do a call to get the details of that/those image(s) pwg.images.getInfo. This is inefficient.
Given the api appears to return a list of categories, I'd expect it to do so. It seems pointless to just return the one that you requested the images list for using pwg.categories.getImages.

When you call pwg.categories.getImages for a category, all resources are returned with just a single category in their list of categories. This is regardless of how many they are linked to. This is an issue if you then wish to unlink a resource(s) (e.g. image), because you do not know whether it will result in an orphan unless you first do a call to get the details of that/those image(s) pwg.images.getInfo. This is inefficient. Given the api appears to return a list of categories, I'd expect it to do so. It seems pointless to just return the one that you requested the images list for using pwg.categories.getImages.

adam closed this issue

2026-10-05 00:14:07 +02:00

adam commented

2026-10-05 00:14:09 +02:00

Hi,
I am wondering if it is possible to get several images from several albums (e.g 3 images from each of 5 categories) in one query? The way to do several requests for this task looks a bit ugly solution, and there is not much documentation on the API.

Hi, I am wondering if it is possible to get several images from several albums (e.g 3 images from each of 5 categories) in one query? The way to do several requests for this task looks a bit ugly solution, and there is not much documentation on the API.

adam commented

2026-10-05 00:14:09 +02:00

Your comment sounds interesting, but this should be raised as a separate issue. The issue I've raised is very different, referring to the list of linked albums returned for each resource when you retrieve the resources in a category.

Your comment sounds interesting, but this should be raised as a separate issue. The issue I've raised is very different, referring to the list of linked albums returned for each resource when you retrieve the resources in a category.

adam commented

2026-10-05 00:14:10 +02:00

Thanks for your attention. I found not much developers activity on this API, so decided to ask in a live thread close to the issue. Also posted this question to PIWI forum. Finally decided to query PIWI DB directly, this appeared to be the fastest and the simpliest method...
Sorry for off-topic message.

Thanks for your attention. I found not much developers activity on this API, so decided to ask in a live thread close to the issue. Also posted this question to PIWI forum. Finally decided to query PIWI DB directly, this appeared to be the fastest and the simpliest method... Sorry for off-topic message.

adam commented

2026-10-05 00:14:11 +02:00

As discussed with @remi-martin yesterday we indeed have to fix this bug. But the result might not be what you expect. I explain. Currently pwg.categories.getImages returns only one category (the current one, a bit useless, to say the least). I can work on it to fix it and provide the same list of categories as the one we see on the page of the photo (picture.php). That would not be the "full" list of albums. Indeed the photo can perfectly be linked to other albums but you don't see them because you don't have access to them.

Reminder: even administrators are subject to the permission system.

In first conclusion: you won't be able to predict a photo would become orphan simply by relying on the list of albums returned by pwg.categories.getImages (or by pwg.images.getInfo by the way). To do that, we could have a second list of "all categories", only provided when connected as administrator.

As discussed with @remi-martin yesterday we indeed have to fix this bug. But the result might not be what you expect. I explain. Currently `pwg.categories.getImages` returns only one category (the current one, a bit useless, to say the least). I can work on it to fix it and provide the same list of categories as the one we see on the page of the photo (picture.php). That would not be the "full" list of albums. Indeed the photo can perfectly be linked to other albums but you don't see them because you don't have access to them. Reminder: even administrators are subject to the permission system. In first conclusion: you won't be able to predict a photo would become orphan simply by relying on the list of albums returned by `pwg.categories.getImages` (or by `pwg.images.getInfo` by the way). To do that, we could have a second list of "all categories", only provided when connected as administrator.

adam commented

2026-10-05 00:14:12 +02:00

Hello there, in piwigo 12 we plan to implement a method called pwg.categories.calculateOrphans, which as it names says, calculates and returns the orphans that would be created if you delete a category. I hope it will help you.

Hello there, in piwigo 12 we plan to implement a method called pwg.categories.calculateOrphans, which as it names says, calculates and returns the orphans that would be created if you delete a category. I hope it will help you.

adam commented

2026-10-05 00:14:13 +02:00

Thanks for looking into this issue.
Returning the list of categories to which the user has access would be what is expected and would avoid us to have to call the pwg.images.getInfo method repeatedly. From this data, we will be able to determine which images belong to which albums and which ones would become orphans if the user deletes an album (as seen by the user).

We could then propose the user to copy images to another album by calling the pwg.images.setInfo method with multiple_value_mode=append for appending the category ID of the targeted album.
For moving images, I expect that we could use the same method with multiple_value_mode=replace for replacing the list of category IDs "belonging to the user". @plg, do you confirm that the method only replaces the list of albums to which the user has access (i.e. the lists provided by pwg.categories.getImages and pwg.images.getInfo)?
And for deleting images, the method pwg.images.delete does the job.

As for the proposed pwg.categories.calculateOrphans method, I do not believe that we really need it because it would return an information we can deduce from a call to the pwg.categories.getImages method without having to make an additional URL request draining the battery of a mobile (it would also be much faster).

I would prefer a method pwg.categories.getOrphans which returns the list of "true orphans" to admins in a format which can be used to display a virtual album of "true orphans" (output similar to pwg.users.favorites.getList).

Thanks for looking into this issue. Returning the list of categories to which the user has access would be what is expected and would avoid us to have to call the `pwg.images.getInfo` method repeatedly. From this data, we will be able to determine which images belong to which albums and which ones would become orphans if the user deletes an album (as seen by the user). - We could then propose the user to copy images to another album by calling the `pwg.images.setInfo` method with `multiple_value_mode=append` for appending the category ID of the targeted album. - For moving images, I expect that we could use the same method with `multiple_value_mode=replace` for replacing the list of category IDs "belonging to the user". @plg, do you confirm that the method only replaces the list of albums to which the user has access (i.e. the lists provided by `pwg.categories.getImages` and `pwg.images.getInfo`)? - And for deleting images, the method `pwg.images.delete` does the job. As for the proposed `pwg.categories.calculateOrphans` method, I do not believe that we really need it because it would return an information we can deduce from a call to the `pwg.categories.getImages` method without having to make an additional URL request draining the battery of a mobile (it would also be much faster). I would prefer a method `pwg.categories.getOrphans` which returns the list of "true orphans" to admins in a format which can be used to display a virtual album of "true orphans" (output similar to `pwg.users.favorites.getList`).

adam commented

2026-10-05 00:14:14 +02:00

Warning: pwg.images.getInfo only returns the list of categories accessible to the current user. Not all categories. So you can absolutely not know if the photo would become orphan if you delete an album. Not reliable at all.

Currently, with multiple_value_mode in {append, replace} you should be able to associate/move/dissociate to albums. The limit is that you have to call pwg.images.setInfo for each photo. We've been discussing this topic with @remi-martin and he suggests we had a new method pwg.images.setCategory with 3 parameters :

image_ids (can be a list, that's the whole point)
action {associate, dissociate, move}
category_id

I like this idea. Much more simple to associate/dissociate images to/from albums. We could also have a specific method for each action : pwg.images.associateToCategory + pwg.images.dissociateFromCategory + pwg.images.moveToCategory (or pwg.images.category.associateTo + pwg.images.category.dissociateFrom + pwg.images.category.moveTo)

As for the proposed pwg.categories.calculateOrphans method, I do not believe
that we really need it because it would return an information we can deduce from
a call to the pwg.categories.getImages

No, you can't deduce the "would be" orphans with pwg.categories.getImages, unless we add a new output field "categories_admin_list" which would not take permissions into account.

The pwg.categories.calculateOrphans method has been added by @MatthieuLP to make the computation as less often as possible, because it's an heavy one and it's useful only a very few times compared to the number of requests to pwg.categories.getImages.

pwg.categories.getOrphans

You mean pwg.images.getOrphans because if a photo is associate to a category then it can't be an orphan. So it would be mean "list of orphans if we delete this category" and it would be the exact same as pwg.categories.calculateOrphans. Please give me more details :-)

Warning: `pwg.images.getInfo` only returns the list of categories accessible to the current user. Not all categories. So you can absolutely not know if the photo would become orphan if you delete an album. Not reliable at all. Currently, with `multiple_value_mode` in {append, replace} you should be able to associate/move/dissociate to albums. The limit is that you have to call `pwg.images.setInfo` for each photo. We've been discussing this topic with @remi-martin and he suggests we had a new method `pwg.images.setCategory` with 3 parameters : 1. image_ids (can be a list, that's the whole point) 2. action {associate, dissociate, move} 3. category_id I like this idea. Much more simple to associate/dissociate images to/from albums. We could also have a specific method for each action : `pwg.images.associateToCategory` + `pwg.images.dissociateFromCategory` + `pwg.images.moveToCategory` (or `pwg.images.category.associateTo` + `pwg.images.category.dissociateFrom` + `pwg.images.category.moveTo`) > As for the proposed `pwg.categories.calculateOrphans` method, I do not believe > that we really need it because it would return an information we can deduce from > a call to the `pwg.categories.getImages` No, you can't deduce the "would be" orphans with `pwg.categories.getImages`, unless we add a new output field "categories_admin_list" which would not take permissions into account. The `pwg.categories.calculateOrphans` method has been added by @MatthieuLP to make the computation as less often as possible, because it's an heavy one and it's useful only a very few times compared to the number of requests to `pwg.categories.getImages`. > `pwg.categories.getOrphans` You mean `pwg.images.getOrphans` because if a photo is associate to a category then it can't be an orphan. So it would be mean "list of orphans if we delete this category" and it would be the exact same as `pwg.categories.calculateOrphans`. Please give me more details :-)

adam commented

2026-10-05 00:14:15 +02:00

Warning: pwg.images.getInfo only returns the list of categories accessible to the current user. Not all categories. So you can absolutely not know if the photo would become orphan if you delete an album. Not reliable at all.

This is not reliable (incomplete) for an admin looking for orphans globally on a server, but this is perfectly fine for an admin or non-admin user managing his/her own photos i.e. for most usages. We miss a user status allowing to create/delete/move/etc. albums and upload/delete/edit photos/videos without access to server management tools.

Currently, with multiple_value_mode in {append, replace} you should be able to associate/move/dissociate to albums. The limit is that you have to call pwg.images.setInfo for each photo. We've been discussing this topic with @remi-martin and he suggests we had a new method pwg.images.setCategory with 3 parameters :

image_ids (can be a list, that's the whole point)

action {associate, dissociate, move}

category_id

I like this idea. Much more simple to associate/dissociate images to/from albums. We could also have a specific method for each action : pwg.images.associateToCategory + pwg.images.dissociateFromCategory + pwg.images.moveToCategory (or pwg.images.category.associateTo + pwg.images.category.dissociateFrom + pwg.images.category.moveTo)

Sure, a single call would be much more efficient. Similarly, I would welcome an update of the methods pwg.users.favorites.add and pwg.users.favorites.remove because we must call them repeatedly.

As for the proposed pwg.categories.calculateOrphans method, I do not believe
that we really need it because it would return an information we can deduce from
a call to the pwg.categories.getImages

No, you can't deduce the "would be" orphans with pwg.categories.getImages, unless we add a new output field "categories_admin_list" which would not take permissions into account.

The pwg.categories.calculateOrphans method has been added by @MatthieuLP to make the computation as less often as possible, because it's an heavy one and it's useful only a very few times compared to the number of requests to pwg.categories.getImages.

pwg.categories.getOrphans

You mean pwg.images.getOrphans because if a photo is associate to a category then it can't be an orphan. So it would be mean "list of orphans if we delete this category" and it would be the exact same as pwg.categories.calculateOrphans. Please give me more details :-)

I understood that the pwg.categories.calculateOrphans method would return the "future orphans" of a user i.e. taking rights into account, but in fact it returns all future orphans on a server, which is the pwg.categories.getOrphans I was proposed. Fine with me.

> Warning: `pwg.images.getInfo` only returns the list of categories accessible to the current user. Not all categories. So you can absolutely not know if the photo would become orphan if you delete an album. Not reliable at all. This is not reliable (incomplete) for an admin looking for orphans globally on a server, but this is perfectly fine for an admin or non-admin user managing his/her own photos i.e. for most usages. We miss a user status allowing to create/delete/move/etc. albums and upload/delete/edit photos/videos without access to server management tools. > Currently, with `multiple_value_mode` in {append, replace} you should be able to associate/move/dissociate to albums. The limit is that you have to call `pwg.images.setInfo` for each photo. We've been discussing this topic with @remi-martin and he suggests we had a new method `pwg.images.setCategory` with 3 parameters : > > 1. image_ids (can be a list, that's the whole point) > 2. action {associate, dissociate, move} > 3. category_id > > I like this idea. Much more simple to associate/dissociate images to/from albums. We could also have a specific method for each action : `pwg.images.associateToCategory` + `pwg.images.dissociateFromCategory` + `pwg.images.moveToCategory` (or `pwg.images.category.associateTo` + `pwg.images.category.dissociateFrom` + `pwg.images.category.moveTo`) Sure, a single call would be much more efficient. Similarly, I would welcome an update of the methods `pwg.users.favorites.add` and `pwg.users.favorites.remove` because we must call them repeatedly. > > As for the proposed `pwg.categories.calculateOrphans` method, I do not believe > > that we really need it because it would return an information we can deduce from > > a call to the `pwg.categories.getImages` > > No, you can't deduce the "would be" orphans with `pwg.categories.getImages`, unless we add a new output field "categories_admin_list" which would not take permissions into account. > > The `pwg.categories.calculateOrphans` method has been added by @MatthieuLP to make the computation as less often as possible, because it's an heavy one and it's useful only a very few times compared to the number of requests to `pwg.categories.getImages`. > > > `pwg.categories.getOrphans` > > You mean `pwg.images.getOrphans` because if a photo is associate to a category then it can't be an orphan. So it would be mean "list of orphans if we delete this category" and it would be the exact same as `pwg.categories.calculateOrphans`. Please give me more details :-) I understood that the `pwg.categories.calculateOrphans` method would return the "future orphans" of a user i.e. taking rights into account, but in fact it returns all future orphans on a server, which is the `pwg.categories.getOrphans` I was proposed. Fine with me.

Sign in to join this conversation.

master

issue-2560-people

translation

16.x

feat/embedding-based-contextual-tagging

issue-2576-search-include-ai-in-search-results

feat/search-ocr-ai

issue-2391-update-menu-design

15.x

detect-container

issue-2386-update-filters-users-activity

issue-2362-add-filters-options-in-admin

issue-2367-imagemagick7

issue-2225-quicksearch-help

14.x

issue-2164-BatchManagerUnitMode-Redesign

13.x

12.x

issue-1657-SVG_Support

issue-1703-historySearchMethod

11.x

2.10

2.9

2.8

2.7

2.5

2.6

2.4

2.3

2.2

2.1

2.0

1.7

1.3

1.6

1.5

1.4

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: adam/Piwigo#727