api

api copied to clipboard

Issue https://github.com/pelias/api/pull/1401 brought up the topic of whether we should enable the categories feature by default across all endpoints.

Currently, we have support for categories which goes back to 2015. The feature consists of a single elasticsearch field with strings analyzed as keyword, so it's very simple but can also be very powerful for industry and interest-specific queries.

When we went to release the feature there was some concern internally at Mapzen about the default taxonomy labels I had selected and the WOF team was preparing an improved list, this work unfortunately never got finished and so the feature was left in an awkward state of half-release, available, yet also hidden from view.

Over the years we've had a bunch of issues and PRs opened regarding categories and the theme seems to be that organizations find them useful.

What would be required to completely release categories as a first-class feature?

• improved documentation including how to use custom category labels
• return categories by default in all geojson feature responses

Are there any concerns regarding the release of categories?

• once released any category labels become part of the public API, making them difficult to change or remove
• some organizations might prefer to opt-out of displaying categories, so it should really be optional?
• not all endpoints support categories, for instance: placeholder or PIP service results might not filter or display as expected

This ticket is open to discuss the pros/cons of enabling the categories feature by default and think through the work which would be required if we decided to go down that route.

cc/ @pelias/contributors

Hi there and Happy New Year :smile:

I think that for those who know this feature, it's already too late, we cannot do breaking changes or delete categories.

The use of categories bypass placeholder, this gives some strange responses when we compare a query with and without the query parameter. /v1/search?text=paris

 1) Paris, France
 2) Paris, TX, USA
 3) Paris, ON, Canada
 4) Paris, TN, USA
 5) Paris Township, OH, USA
 6) Paris Township, IL, USA
 7) Paris Township, OH, USA
 8) Paris, ME, USA
 9) Paris, IA, USA
10) Paris, Indonésie

/v1/search?categories=&text=paris

 1) Métropole du Grand Paris, France
 2) Paris, France
 3) Paris, France
 4) Paris, TX, USA
 5) Paris Township, OH, USA
 6) Paris Township, IL, USA
 7) Paris Township, OH, USA
 8) South Paris, ME, USA
 9) Paris, NY, USA
10) Paris 19, Paris, France

At this time, there are no repositories containing all the categories, each repository create its own categories without a superior authority/global taxonomy. This could introduce mistakes (or not). The counter argument would be that users will not be able to add their own.

I found something else, there are no categories for addresses (from OSM and OA) and streets. It might be interesting to have a category for queries like categories=admin,streets,transports (when we need cities + streets + stations).

My last thought is : the categories need a bit more work before seeing the daylight :sweat_smile:.

Hey @Joxit I already filed an issue for that one. :) https://github.com/pelias/api/issues/1374

I do like venues from OSM since then they can be easily updated and customised according to each user's preferences. Including venues from other sources could be trickier however if they come pre-categorised.

Yeah at the moment there is no 'canonical list' of categories as such. The best we have so far is the OSM mapping file which is based on my original proposal.

Having this feature properly documented would be super valuable!