Provide APIs to sync with gnome-maps

[Sumaid]

This is part of the ongoing discussion to revive the work in nextcloud maps. I will be proposing a project to sync gnome-maps with nextcloud. Current requirements from the gnome-maps side are
1)Favorites:
This is the most important feature which is required. Having access to your favorite places
where ever you go, is very useful.
Favorites are just one of many possible categories we can have, so API should allow for passing of places in any category. This is very simple to do since we can just have an attribute which stores type of place.
I am still shaping and understanding the proposal so I'll appreciate any ideas and suggestions.

[Sumaid]

Data in gnome-maps is stored in a JSON file with the following schema:
{
place:
type:
added:
}
place is an instance of class Place which has attributes:
osm_id, osm_type,name,location,bounding_box,place_type,street_address,street,building,
postal_code,area,town,state,country,county,country_code,continent.

Important attributes of location are longitude, latitude.

[julien-nc]

Hi there!

I think we don't want to store osm-related information in NC Maps. A favorite could be defined by:

• name
• type/category
• latitude
• longitude
• note/comment
• date of last modification

The way I see it, the API would make it possible to:

• get all favorites
• get those more recent than a given date
• edit a favorite
• delete
• add

What do you think?

I just checked Gnome-Maps v3.30.1, there's a button to "switch to favorites" but it's disabled. Is the local favorite management feature ready yet?

[Sumaid]

@eneiluj That's what I had in mind, the attributes you mentioned are the only relevant ones.
But I was thinking maybe we should at least store reference to osm node id(if it exists) with the favorite place? Since there can be different OSM nodes on the same location.

Currently, favorite places are stored as a list of OSM nodes. This does not allow users to assign nicknames to favorite places. Moreover, users can not mark
a place as a favorite which is not part of OSM. Hence the design of favorites(or other categories) needs to be simplified. Favorites can just have attributes which you mentioned. Simplifying favorite management design will also be part of SoC.

cc: @mlundblad (Gnome-Maps Maintainer)

[julien-nc]

Hummm yeah, like you said, a favorite can also be in the middle of nowhere and there's no OSM node to associate with. Also, it's kind of redundant because both OSM nodes and favorites have coordinates. An OSM node could be deduced from a favorite coordinates. It can be ambiguous when there are multiple OSM entities in one place but it doesn't seem problematic.

Anyway favorites don't have to be stored the exact same way in Gnome-Maps and in NC-Maps. If you want to keep a reference to an OSM node in Gnome-Maps, you can. I just think it shouldn't be part of the API to sync with NC-Maps 😄.

After we get a third opinion I'm ready to implement the API in my rework-eneiluj branch! Maybe @jancborchardt, @rullzer, @juliushaertl or @MorrisJobke have something to add.

[juliushaertl]

name
type/category
latitude
longitude
note/comment
date of last modification

That sounds reasonable to me. Having the osm node somewhere in the metadata however also makes sense to me. If we want to have this a bit more flexible we could just have a metadata field, which can contain some json data for additional information. In case we add that, however we should probably have some schema for that.

[MorrisJobke]

In case we add that, however we should probably have some schema for that.

Or some type.

[Sumaid]

@juliushaertl If we are keeping metadata field only for OSM reference, then we can just store
osm_id(unique id with any osm node).
But maybe @eneiluj is right, as far as nextcloud maps is considered, we probably don't need anything related to OSM. That can be taken care of by gnome maps locally.

[Sumaid]

Having osm identifier could help if gnome maps loads favorites from the nextcloud server, and want to get more details by referring to corresponding OSM node(If it exists). Maybe @mlundblad can comment on this use case in gnome-maps.

[mlundblad]

It's actually a pair (OSM type and OSM ID) identifiying objects in the OpenStreetMap database. An object is of any of the three types "node", "way", or "relation". A node is a single point (with a lon/lat), a way is a an ordered list of references to nodes (could be road segments, and things like buildings, the way is then mapping the outline of the building and is then closed, meaning the list contains the same node reference twice, at the beginning and end), and lastly relation, which contains references to other objects (of any type, including other relations) with associated roles.
The ID is unique within each type (e.g a node can have the same ID as a way).

I'm thinking maybe this could be an optional extension to the stored places. Or maybe there could be a client-specific extension. Something like this (expressed in something JSON:ish):

place {
lon: ...
lat: ...
name:
notes:
extensions: [
x-gnome-osm-type: "node"
x-gnome-osm-id: 12345
]
}

[mlundblad]

I just checked Gnome-Maps v3.30.1, there's a button to "switch to favorites" but it's disabled. Is the local favorite management feature ready yet?

When searching for a place, in the "place bubble" that appears attached to the "pin" on the map there's a "star" button that is a toggle. Selecting it will "fill" this star and the place will then appear in a menu that is accessed by the star button in the title bar (that button will be clickable when there are saved favourites available).

[Sumaid]

I'm thinking maybe this could be an optional extension to the stored places. Or maybe there could be a client-specific extension. Something like this (expressed in something JSON:ish):

place {
lon: ...
lat: ...
name:
notes:
extensions: [
x-gnome-osm-type: "node"
x-gnome-osm-id: 12345
]
}

We'll need to change this on the client side right? I mean the way favorites are currently stored as places(which get identified with osm points) does not allow renaming or marking any place between streets as favorite. So changing favorite management to a simpler schema like this will prove very useful.

[julien-nc]

@mlundblad Ok thanks, I just tried to find a right-click menu entry to add a favorite and there wasn't.

I couldn't try to add a favorite the way you said because it crashes when I search for something in the top bar. I'll check if there already is a related issue in Gnome-Maps project...

@Sumaid Gnome-Maps does not necessarily need to be changed but if you keep it like that it's going to be tricky to sync with other systems that don't store OSM-related information.

So, adding an "extension" (with JSON or whatever inside) parameter to the NC Maps API and field in DB scheme seems to be a flexible way to let clients add extra information structured as they like.

[mlundblad]

@mlundblad Ok thanks, I just tried to find a right-click menu entry to add a favorite and there wasn't.

I couldn't try to add a favorite the way you said because it crashes when I search for something in the top bar. I'll check if there already is a related issue in Gnome-Maps project...

Yes, the Nominatim changed their API (the return types of the JSON) so the geocode-glib library segfaulted. It should be fixed in geocode-glib 3.26.1 (with a fix to make it resiliant).

[julien-nc]

There's a first draft of Rest Favorite API in rework-eneiluj branch. It's basic and functional. It's not used by the app UI yet.

Now I wonder if keeping category as a text field in favorites table is a good idea. It would be nice to be able to rename a category without editing all related favorites. It would also be nice to set a color for each category.

If we add a "category" table and "category" field in favorites table becomes a reference, what about the API? Should we add routes to manipulate categories or should we try to make it transparent, avoid the color field in the API and still expose category as a string field?

[tacruc]

@eneiluj what is the route for in the API?

       [
            'name'         => 'favorites_api#preflighted_cors',
            'url'          => '/api/1.0/favorites{path}',
            'verb'         => 'OPTIONS',
            'requirements' => ['path' => '.+']
        ],

maps/appinfo/routes.php

Line 36 in 768eabc

[

[julien-nc]

It's a route making NC provide CORS headers allowing API calls to be made from another browser. It's useful if a web app wants to sync maps favorites.

Programmatical HTTP clients don't care about CORS but browsers do.

A concrete example of why this route is useful is Cospend. There's a feature in Cospend to access projects of another NC instance with the API, making Cospend act like a Cospend client. Such API calls don't work without CORS headers, most browsers refuse to access such API if cross origin requests are not allowed.

[jancborchardt]

Related to CORS (Cross-Origin Resource Sharing) we also have this issue in the server: nextcloud/server#3131 :)

[julien-nc]

NC Maps favorites API has been mentioned in osmandapp/OsmAnd#2750.

[GIJack]

Just adding, that gnome-maps should also likely be ported to use gnome-online-accounts at some point as opposed to its own login.

It would make it easier if the GOA had an option for "maps" next to files, contacts, calendar and docs

[jancborchardt]

@GIJack are you involved with GNOME Maps and is that something they are doing or will be doing? Or is this a proposal? :) (If the latter, it should be proposed with them instead of here – we are very much in favor of it as doing it through GNOME Online Accounts makes it much simpler! :)

[GIJack]

just proposal. want decent maps :(

[rugk]

Btw let's not make it too GNOME maps specific, if we have a general Ali, that would be useful and solve a lot of issues for other apps like:

• Osmand Enable synchronisation of favourites osmandapp/OsmAnd#2750 and
• OrganicMaps Bookmark synchronization/online backup organicmaps/organicmaps#622