search

GIScience / ohsome-api

API for analysing OpenStreetMap history data
https://api.ohsome.org
GNU Affero General Public License v3.0
47 stars 8 forks source link

Discussion: Make clipGeometry parameter explicit on all endpoints? #250

Open SlowMo24 opened 3 years ago

SlowMo24 commented 3 years ago

This is a follow up of #245 , see https://github.com/GIScience/ohsome-api/issues/245#issuecomment-966968555.

The question arose if clipGeometry could be renamed to clipResult and added to all endpoints. Currently this is done, setting clipGeometry=True for any endpoint where it cannot be specified. E.g. the contributions endpoint will only return contributions within the given area of interest. Making it explicit would enable the user to get all contributions to the intersecting geometries.

bonaparten commented 3 years ago

I also am for having it added to all endpoints. I think this is a coherent and expected behavior. I am not sure regarding the name since it is the geometry that is clipped. Why would you like to have it renamed?

SlowMo24 commented 3 years ago

For the user it may seem strange that you clip the geometry for a contributions or aggregation endpoint. The idea was that we have a result that is what the filter returns and then some clipping and post-processing that will create the return value. In that case its the result that is clipped, no matter its type. But clipGeometry may be just as reasonable, if it is well documented!

bonaparten commented 2 years ago

I get the point, but I do not totally agree with that point, since in our case "clip" means to cut the geometry (no clipped result without clipped geometry). I understand "result" as what is given back at the end, when the clipping process already happened. Definitely, it should be better documented.