[Places] Understanding the rationale behind the categories object

[Matthias Hersche (ma77hiaz)]

Category Feedback

After studying the categories object, I would like to understand the rationale behind its structure.

So there's the "primary" and "alternate" key.
For example: {'primary': 'pizza_restaurant', 'alternate': ['restaurant', 'italian_restaurant']}

As I understand it, "primary" always contains the most specific category and "alternate" contains the broader categories from the taxonomy, going from broad to more specific.

Let's take the duckdb query form the docs as an example:

    SELECT
       id,
       names.primary as name,
       confidence AS confidence,
       CAST(socials AS JSON) as socials,    -- Ensure each attribute can be serialized to JSON
       geometry                             -- DuckDB understands this to be a geometry type
    FROM read_parquet('s3://overturemaps-us-west-2/release/2025-03-19.0/theme=places/type=place/*', filename=true, hive_partitioning=1)
    WHERE categories.primary = 'pizza_restaurant'
    AND bbox.xmin BETWEEN -75 AND -73       -- Only use the bbox min values
    AND bbox.ymin BETWEEN 40 AND 41         -- because they are point geometries.

If I want a query that includes all restaurants, it would have to look something like this:

    SELECT
       id,
       names.primary as name,
       confidence AS confidence,
       CAST(socials AS JSON) as socials,
       geometry
    FROM read_parquet('s3://overturemaps-us-west-2/release/2025-03-19.0/theme=places/type=place/*', filename=true, hive_partitioning=1)
    WHERE categories.primary = 'restaurant'
       OR 'restaurant' = ANY(categories.alternate)
       AND bbox.xmin BETWEEN -75 AND -73
       AND bbox.ymin BETWEEN 40 AND 41;

Here, I have to search within "primary" and "alternate", to make sure I catch all the restaurants.

For me, it would make more sense, to just have the "categories" column be one array that includes all the categories in one array:
[pizza_restaurant', 'italian_restaurant', 'restaurant']

In this case, I could do the query like this:

    SELECT
       id,
       names.primary as name,
       confidence AS confidence,
       CAST(socials AS JSON) as socials,
       geometry
    FROM read_parquet('s3://overturemaps-us-west-2/release/2025-03-19.0/theme=places/type=place/*', filename=true, hive_partitioning=1)
    WHERE 'restaurant' = ANY(categories)
       AND bbox.xmin BETWEEN -75 AND -73
       AND bbox.ymin BETWEEN 40 AND 41;

And if I only want the primary category, I do this:
In this case, I could do the query like this:

    SELECT
       id,
       names.primary as name,
       confidence AS confidence,
       CAST(socials AS JSON) as socials,
       geometry
    FROM read_parquet('s3://overturemaps-us-west-2/release/2025-03-19.0/theme=places/type=place/*', filename=true, hive_partitioning=1)
    WHERE categories[-1] = 'pizza_restaurant'
       AND bbox.xmin BETWEEN -75 AND -73
       AND bbox.ymin BETWEEN 40 AND 41;

Let me hear your thoughts!

Dependency with other categories, if any.

No response

[Stefan (sfkeller)]

Dear Marc Marc Prioleau (@mprioleau) : This question has been unanswered for some time
=> Can you briefly explain why?
=> And can you eventually give some hints (since this is a rather fundamental question about using the Places theme)?

I'm asking because the documentation on Overture Maps is still very poor. And if I understand the membership conditions (https://overturemaps.org/become-a-member/ ) correctly, 80(!) engineers should be working on the project (since the four steering committee members each contribute 20(!) FTE engineering headcounts to the project).

[Dana Bauer (danabauer)]

Hi Matthias Hersche (@ma77hiaz). I appreciate your thoughts on this issue. We have been exploring new taxonomies for places and other themes but we have yet to reach consensus. You might be interested in this proposal from Jonah Adkins (@jonahadkins): OvertureMaps/schema#227.

[allukac]

Matthias Hersche (@ma77hiaz) hi, we are currently trying to develop a higher hierarchy for entities categories, that might be of help here. We will this use case into consideration as well.

[Jonah Adkins (jonahadkins)]

proposing an iterative change in a new file in OvertureMaps/schema#345

[Matthias Hersche (ma77hiaz)]

Dana Bauer (@danabauer) wow, this looks amazing! This would be on top of the existing Overture categorization, do I understand that correctly?
So I guess the original way of categorizing with "primary" and "alternate" would remain?

Jonah Adkins (@jonahadkins) And this iterative change would be a move towards a new structure, correct? Keeping the primary Overture category as-is, but add those additional columns with theme, topic, etc. to bring more hierarchy into the whole thing?
Would your goal be to eventually exchange the current category column for this taxonomy? Like an array with [theme, topic, subtopic, variant, subvariant] (from broad to specific)?

Overall, great ideas!

[Jonah Adkins (jonahadkins)]

Matthias Hersche (@ma77hiaz) yeah the suggestion is to leave the current one as is, and develop this new one separately. not sure if the new one would replace or just having it as a look up for those who need it.

[Stefan (sfkeller)]

I'm still looking forward to a better documentation and explanations about the modeling of the attributes category.primary and category.alternates.

I've analyzed the Places data and that's what the data "says" by the example of restaurants:

1. Up to half of the categories are NULL
2. Some features have category.primary=restaurant and category.alternates is NULL
3. Some features have category.primary=pizza_restaurant and category.alternates=[italian_restaurant]
4. Some features have category.primary=pizza_restaurant and category.alternates=[restaurant]

It seems that currently Places theme is almost unusable when trying to get all restaurants - unless you are just interested in the most specific primary category, like pizza_restaurant.

If you want to show all restaurants (including specialized ones) users think, that category.primary=restaurant is all you need (as also shown in the DuckDB examples) - but they will miss half of those features which are tagged pizza_restaurant (see point 3 above and some stats in P.S. below).

Now following questions arise:

1. Ad 1. and 2. Why so many NULLs?
2. Ad 3 and 4: Is category.alternates a means to indicate alternate categories - or next broader taxonomix term or both?

My proposal: Both, e.g. category.primary=pizza_restaurant and category.alternates=[italian_restaurant, restaurant]. I appreciate the schema with category.primary and category.alternates - but the list of category.alternates should contain both, "real" alternate categories as well as the broader terms.

P.S. Some stats from Places in the bounding box of Switzerland:

[Dana Bauer (danabauer)]

Hey folks. Here's an update on our ongoing taxonomy work in places: https://docs.overturemaps.org/guides/places/taxonomy/

[Stefan (sfkeller)]

So this is a breaking change which renders the open questions above above obsolete?

[Dana Bauer (danabauer)]

Stefan (@sfkeller) We intend to keep the original categories property available for several months alongside the new basic_category property (added in our October 2025 release) and taxonomy property (added in our December 2025 release release). The docs now include information on mapping across the properties.

[Stefan (sfkeller)]

Sorry: I can't find updated docs newer than 9 montgs old:

• This is one year old https://github.com/OvertureMaps/schema/blob/main/docs/schema/concepts/by-theme/places/index.mdx
• This was updated 9 months ago: https://github.com/OvertureMaps/schema/blob/main/docs/schema/concepts/by-theme/places/overture_categories.csv

[Dana Bauer (danabauer)]

The docs are here: https://docs.overturemaps.org/guides/places/taxonomy/