For 1.8.0, we had quite some discussion in #1064 (and in #1094 and #1112), about the exact API we wanted for STRtree. In the end we settled on adding query_items() and query_geoms methods (in addition to query) instead of adding a keyword (like return_geometries=True/False) in query(). #1112 also added the functionality to pass custom items to the the STRtree(.., items=..) constructor.

But in #1251, where I merged the pygeos functionality with this Shapely interface, we had again some discussion about this, indicating that it might not yet be fully resolved.

One of the discussion points is the usage of the term "items" (#1251 (comment)). While the method is called query_items(), I used "index" in the update of the docstring.

Return the index (or stored item) of all geometries in the tree
with extents that intersect the envelope of the input geometry.

The returned items may be identified by an integer index (default) or
arbitrary item values (optional) if those are provided when
constructing the tree.

But this triggered some comments about it (eg #1251 (comment) or #1251 (comment)). While I think we can certainly get agreement on how to understand the default behaviour, it might point to the fact that the API is not yet really ideal (also given the fact that we have a hard time to clearly / succinctly explain this in the documentation).

Some other issues with the current naming in the API:

• The default is to return integer indices (if the user only provided geometries to the STRtree constructor), but the method is actually called query_items() using "items".
  (I personally think that most people will never pass explicit items, but will rather use the indices)
• The query_bulk() method only returns integer indices, and never items (even if the user passed those in the constructor), creating some more inconsistency. And the same applies to nearest_all.
  (The reason for this is that this methods takes an array of query geometries as input, and so returns indices into both the tree and input geometries. Alternatively, we could require that you pass items as well to the query_bulk method, but this would further complicate this method)

So possible outcomes:

• Decide we are fine with how it is now, and maybe only tweak the docstring a bit further.
• Reconsider the ability to pass custom items, to avoid the dichotomy between "items" and "indices" (and it easy to mimic this as a user).
• Reconsider the full API (i.e. the different options mentioned in Store indices instead of geometries in STRtree + option to keep returning geometries #1064 (comment): a keyword, different methods, different classes)

cc @sgillies @caspervdw @brendan-ward @mwtoews