Feature Request: Machine API for map creation

[jvmatl]

Apologies in advance if such a thing already exists -- I could not find evidence of such an API in the documentation, and I have been working my way through the documentation I can find as I get up to speed.

Is your feature request related to a problem? Please describe.

I work for a company that makes/sells/uses GPS tracking devices. My 'grand vision' is to host a private umap server instance for my company, (and play nice by pointing it to a tile cache or tileserver we pay for :^) ) and then having an automated cron job that generates maps and emails them out (e.g. Every Friday afternoon, we could auto-generate a map that we send to a trucking company with a map of where all their assets are, with each map-marker enhanced with whatever metadata is useful.)

I have prototyped the kind of thing we want to create by

• manually creating the map,
• manually creating layers
• manually setting all the map-settings I want (appearance, security, what buttons to show, etc.)
• uploading a computer-generated CSV file of all the markers into the proper layers
• and then manually generating a 'non-editable' link to the map which could then be sent to a customer.

Describe the solution you'd like

I would like to be able to send messages to a published REST API to:

• create a map, get back an ID
• create layers within a map, with properties, get back an ID
• set map and layer settings, given IDs and property values
• upload/import data to layers, given a layer ID and a data file
• generate a read-only map link for a given map ID

I know these APIs must exist in some form, since your web app uses them, but I want to be able to access them from, say, a cron job running in python, so there are probably also authentication considerations (e.g. maybe users of the map server need to be able to generate API keys that can be used to auth against the APIs? I obviously can't have my server use my google oauth login (at least i don't know how,) and I probably don't want to post the root username and password in API requests.

Describe alternatives you've considered

It might be possible to automate most of the actions I need with some headless web-app automation, like Selenium, but that seems like a silly waste of effort, and it would only benefit me, not the whole uMap-using community.

Side note Would also be nice if it were possible to set some sort of expiration date on a map, so these things would clean themselves up after some amount of time. But it'd be silly to put up a separate feature request for that at the moment, if the main feature doesn't exist.

[jvmatl]

As I said, these APIs obviously exist, since the uMap web app already does these things, so maybe this is mostly a documentation request? Other than possible the API key thing, maybe all I need is a pointer to somewhere I can learn the API names and arguments.

If I can find (or you implement) this API, my intent would be to create a public python or golang library to encapsulate the relevant parts of the API with helper functions to abstract away the web stuff and let users focus on their data.

[yohanboniface]

Hi @jvmatl thanks for taking the time to detail your needs!

As you said, there is a "sort of API", given the web app communicates with the backend through REST requests. But it's not only a matter of documenting it, here a few steps that would be needed to make this API public:

• as you spotted, we'd need an auth mechanism dedicated to the API
• at this time, datalayers POST/GET contain both data and settings in a single geojson, this needs to be separated I'd say
• there is no endpoint for getting a full map data (this export is made client side)
• indeed document it

uMap data model is quite simple, it's roughly only a Map and DataLayers, so you may still use what's already there just by looking at what the client send to the server. But indeed this could change without clear notice.

About auth, in a first step, you could either use a single account for all your maps, or use anonymous maps and use the cookie as auth.

Making this API stable and public is on our roadmap (#175). We'll try to make it on top of our priorities, but at this stage I'm not able to give you an approximate time for delivery.

Also, possible workaround is using playwright, as we do in our integration tests: https://github.com/umap-project/umap/blob/master/umap/tests/integration/test_owned_map.py

Would also be nice if it were possible to set some sort of expiration date on a map, so these things would clean themselves up after some amount of time.

This is a need I've already heard, so I'd say let's open a dedicated issue :)

[jvmatl]

Cool, thanks for the feedback.

I didn't know about playwright, but I might be able to cook something up that accomplishes the same effect I'm looking for. It's obviously not ideal - it's almost humorously inefficient to spawn a headless virtual browser to drive the umap webserver to do what I want... but I kind of like it :smile: -- and for the low volume of maps I expect to be making in the near-term, efficiency is totally irrleveant. Sounds like I have a new tool to learn..