# POI Reviews in OsmAnd

## Summary

To make OsmAnd an even more viable Google Maps alternative, we would like to add support for reading -- and, eventually, writing -- POI reviews. This section summarises key points of the proposal.

* Minimal viable product (MVP): **display reviews from Mangrove** in OsmAnd, in place details context menu.
* **Preprocess reviews into OBF** to allow offline use.
* **Reuse existing object details lookup logic** to populate review information.
* **Resolve OSM node ids during preprocessing** to allow for efficient lookup.
* Submitting new reviews from OsmAnd will be designed and implemented in the future.

The rest of this document is organised as follows:

* _Background_ section presents the relevant context: where review data can be obtained, how other systems handle reviews, what existing OsmAnd functionality is relevant to reviews.
* _Design_ discusses the technical details of the proposal: the data flow, how the reviews are to be represented in the system.
* _Discussion_ attempts to justify the proposals.

## Background

Relevant OsmAnd issue: {%preview https://github.com/osmandapp/OsmAnd/issues/11111 %}

### Prior Art

Some OSM–based apps do support reviews:
* [Mapy.com](https://mapy.com) manage [their own review database](https://help.mapy.com/ratings/) and also use country-specific external services.
* [MapComplete](https://mapcomplete.org) uses Mangrove dataset (see [below](#Review-Datasets)).

### Review Datasets

We identified two services that provide review datasets where the licence is permissive (at least CC-BY-SA) and the provenance of reviews is clear.

| Dataset | License | # reviews | # OSM places
| ------- | -------- | -------- | ------|
| [Mangrove](https://mangrove.reviews) | CC-BY | 3500 | 1000 |
| [Lib.reviews](https://lib.reviews) | CC-BY-SA | 2000 | 300 |

These datasets are currently very small. Are there any large-scale, freely available datasets that can be used here? Some candiates:

* [Yelp Open Dataset](https://business.yelp.com/data/resources/open-dataset/) -- contains 7 million reviews, but can only be used in academic research.
* Research datasets published on [Kaggle](kaggle.com/datasets) or [Zenodo](https://zenodo.org). These websites offer a number of datasets under CC-BY or similarly permissive licences, but many of these were scraped or otherwise extracted from commercial platforms (TripAdvisor, OpenTable, Zomato etc.), possibly violating platform's Terms of Service, and it is dubious whether the publishers have the right to apply a CC licence. Example datasets:
* [Zomato: Indian restaurants](https://www.kaggle.com/datasets/prepinstaprime/tomato-reviews/data) (Kaggle)
* [Korean restaurants](https://www.kaggle.com/datasets/ninetyninenewton/kr3-korean-restaurant-reviews-with-ratings) (Kaggle)
* [TripAdvisor European Restaurants](https://www.kaggle.com/datasets/stefanoleone992/tripadvisor-european-restaurants) (Kaggle)
* [TripAdvisor European Restaurants](https://zenodo.org/records/14622324) (Zenodo)

### Reference OsmAnd Functionality

* *consumption of non-OSM data*: OsmAnd supports displaying Wikipedia articles about POIs. We can take this as a a reference on how supplementary information is handled and displayed.
* *writing and submission of user-created content*: OSM notes submission UX can be taken as a reference when designing a review submission workflow.

## Design

### Data Flow

Data flow when consuming reviews. Data sources other than Mangrove are shown for illustration only, they are not part of the MVP.

flowchart LR
    mangrove(Mangrove API) --> csv[/review CSV/]
    libreviews(LibReviews dump archive) --> json[/review JSON/]
    otherSource(... other data sources ...) --> otherFormat[/... other formats .../]
    csv --> mapcreator(OsmAndMapCreatorUtilites)
    json --> mapcreator
    otherFormat --> mapcreator
    mapcreator --> obf[/review OBF/]
    obf --> app(OsmAnd App)

1. Use scripts to download the datasets from sources such as Mangrove or Lib.reviews.
2. Run [OsmAndMapCreatorUtilities](https://github.com/osmandapp/OsmAnd-tools/blob/master/java-tools/OsmAndMapCreatorUtilities/src/main/java/net/osmand/MainUtilities.java) to convert the reviews from source formats to [OBF](https://osmand.net/docs/technical/osmand-file-formats/osmand-obf). This involves:
1. [resolving OSM node ids](#OSM-Node-Id-Resolution) for each review;
2. [encoding review data](#Review-Data-Encoding) as OSM-style tags;
3. calculating aggregate ratings (average rating, number of reviews) for each reviewed POI.
3. Make the reviews OBF file(s) available via OsmAndServer so they can be downloaded by the app.
4. The app uses the data in OBF files to [display](#Reviews-UI) aggregate ratings and reviews alongside other POI details

### Review Data Model

record ReviewedPlace(
    long osmId,
    int averageRating,
    List<Review> reviews
) {}

record Review(
    int rating,     // a numerical rating in the range 1..100
    String opinion, // an opinion string; can be in any language
    String author,  // the author name, as provided by the source system
    LocalDate date, // the date when the latest version of the review was published
    URI sourceUrl   // an URL to the review in the source system
) {}

### Review Data Encoding

For compatibility with existing metadata storage, the review data will be encoded using OSM-style tags. All reviews for a given POI will be stored in a single tag, `reviews`, encoded as JSON. Sample value of the `reviews` tag:

[
    {
        "rating": 80,
        "opinion": "excellent espresso",
        "author": "enigal",
        "date": "2025-07-13",
        "link": "https://mangrove.reviews/list?signature=abcdef"
    },
    {
        "rating": 60,
        "opinion": "The service could be better.",
        "author": "pangloss",
        "date": "2025-07-11",
        "link": "https://some.review.site?review_id=12345"
    }
]

The reviews will be ordered from newest to oldest. In addition, the aggregate information will be stored as tags:

reviews:aggregate_rating = 70
reviews:count = 2

### Review Lookup

_TODO: `AmenitySearcher` only allows a single Amenity with a given OSM id. Modify this logic to allow _auxiliary data_ with the same OSM id as an existing POI id._

### OSM Element Id Resolution

The Mangrove reviews that originated in MapComplete have the client id which looks like this: `https://mapcomplete.org/food.html?z=18.2&lat=47.47272757562337&lon=-0.5461215438830322&q=Love%20e%20Basta#node/7419566220`.

This client id directly specifies the OSM node/way/relation id, making the resolution trivial. We propose to constrain the MVP to these reviews only.

For other Mangrove clients, or other datasets, the resolution might need to rely on the lat/lon coordinates and the place name, which are commonly available. If necessary, this resolution algorithm will be designed post-MVP.

#### Partial matches

Consider the pieces of data we have available for resolution:

* _location_: lat/lon
* _name_: place name
* _id_: OSM element id (e.g. for MapComplete reviews)

When not all of these fields match between the OSM element and the reviews, should we still attach reviews to the OSM element? Let us consider different match scenarios. The matches that should be sufficient to attach a review are indicated in bold.

* **_location_ + _name_ + _id_**: full match, the reviews are for this place.
* **_location_ + _name_**: this is likely the same place. The element could change, for instance when a node was changed to a way, but location and name are likely unique enough to identify the place.
* _location_ + _id_: an OSM element can denote different businesses over time; if the name does not match then the reviews might no longer be relevant.
* **_name_ + _id_**: this is likely the same business. The coordinates could change due to correction of map inaccuracy or business actually changing the location.
* _location_: multiple amenities can exist at the same location
* _name_: there are multiple amenities with the same name
* _id_: an element can denote different businesses over time

To handle the positive partial match cases, we would need to use up-to-date OSM data to find the corresponding id (in case of _location_ + _name_) or location (for _name_ + _id_). To simplify the initial implementation, we will not do that for the MVP and will only attach reviews that match on all three fields. This means that potentially relevant reviews might not be displayed for a place, if its OSM element or its location changed since the review was published.

_TODO: to verify a name match_ we would also need to reference with current OSM data, or filter in the app_.

### Reviews UI

_Reviews_ collapsible section will be shown in POI context menu. When collapsed, it will show the average star rating and the number of reviews.


When expanded, the section will contain N=10 most recent reviews. Only the first M=200 characters of each review will be shown.


Selecting a review will open the source URL in the default web browser.

When there are more than N reviews, we can consider adding a button at the bottom of the list to navigate to the full list of reviews. This will not be included in the MVP.

## Discussion

Here we discuss the motivation for the proposed design decisions and implementation plan.

### Return on Investment

The Mangrove dataset is currently miniscule. Is integrating it into OsmAnd worth the development and ongoing maintenance cost? We contend that it is:

1. Initially, with the small size of Mangrove dataset, the bandwidth and processing cost of distributing the review bundles will be negligible compared to the maps and Wikipedia bundles. The operational cost should also be minimal, given that the download and preprocessing of Mangrove data can be easily automated.
2. OsmAnd with its [2.5 million monthly active users](https://osmand.net/blog/stats-15/) can contribute to the growth of the Mangrove review dataset. For this, writing reviews in OsmAnd will be crucial, so the MVP should be seen as a first step.
3. Once the MVP is implemented, adding a new, more comprehensive review dataset will be relatively easy. If OsmAnd was able to acquire such a dataset (see [Review Datasets](#Review-Datasets)), it would provide additional reason for new users to adopt it as a more comprehensive Google Maps replacement.

### Reading vs. writing

Google Maps, Mapy.com and MapComplete both display and let one write reviews. Here we focus on the review display scenario. While authoring reviews in OsmAnd is important and might be key to increasing the volume of available reviews, it is largely independent of consumption and can be designed and added later. Just displaying reviews is valuable in its own right, and many (most?) map users benefit from the reviews without having ever written one.

### Use of Mangrove

[Mangrove](https://mangrove.reviews) is a review infrastructure built and maintained by [Open Reviews Association](https://open-reviews.net), whose purpose is to enable the creation of open data ecosystem for reviews. We selected Mangrove for the MVP integration for the following reasons:

1. Mangrove is already used in the OSM ecosystem: it is integrated into MapComplete
2. The resolution of OSM node/way id for a review that was submitted via MapComplete (a significant portion of the reviews in this dataset) is straightforward.

Once the MVP is complete, it will be easy to add other data sources by simply implementing transformation from the source format to the review data model described above.

### Offline vs. online

We propose to not access the datasets online and rely on downloaded data bundles for the following reasons:

1. It is consistent with the offline-first principles of OsmAnd.
2. Preprocessing of the reviews and indexing them by OSM node id allows for efficient lookup.
3. It confines the dataset-specific parsing and resolution logic to OsmAndMapCreatorUtilities and avoids application bloat.
5. The nature of POI reviews is such that data freshness in the order of weeks is perfectly sufficient. It is fine to only have the review set updated once a month.

### Plugin

Some OsmAnd functionality is controlled by enabling relevant plugins. This helps avoid clutter in the UI. We argue that for the purpose of reading reviews, a plugin is not necessary: presence of reviews is triggered by the user downloading the review bundle from the server.

Review submission, however, will likely benefit from being represented as a plugin, so that the "submit review" button is only visible if the user chooses to enable the plugin. In addition, submission is dataset-specific, so dedicated plugins can be developed for adding reviews to Mangrove, Lib.reviews and so on.

### Future Work

Here are some directions of future work, once the review MVP is implemented.

* review submission
* more comprehensive node id resolution
* filtering search results by review score
* ingesting more review datasets
* handling reviews in multiple languages
* editing own reviews