API for location Features

[ErikDB87]

Hi all,

I'm setting up Reitti for myself and my girlfriend, and I'm trying to figure out the cleanest way to feed it location data given a slightly non-standard setup.

My own phone (Android) runs OwnTracks and reports straight to my openHAB instance, so that would work out of the box with Reitti. But my girlfriend uses an iPhone, which smothers OwnTracks, so I added in geolocation from iCloud. In openHAB I then 'combine' both sources.

I'm able to create JSON's in whatever needed format, and make some HTTP request, but I haven't found documentation about how that would work with the API. I only read about 'importing' data, which seems to be different from 'getting live data'...

Could anyone help me out, and/or point me in the right direction?

Thanks in advance!

[dgraf-gh]

Hi @ErikDB87

first, I have never used openHAB so this is a little guess work here.

If both report to openHAB maybe have a look how the HomeAssistant integration works. There is propably a way to do this also in openHAB.

https://www.dedicatedcode.com/projects/reitti///latest/integrations/home-assistant/

There it takes the latest known location, pack it into a json which is compatible with the owntracks format and send this periodically into reitti every x seconds. X should be something around 30 seconds.

The only important part to know there is that the timestamp of a point is the identifier. So, this needs to change on every request.

Let me know if this helped. If you figure it out we can add that also to the docs.

[ErikDB87]

Thanks for your answer, @dgraf-gh! From your link I deduced the necessary info for an HTTP Post request. And then I saw that this documention was already provided: https://www.dedicatedcode.com/projects/reitti/4.0/api/ingest/

I hadn't really looked at that page, as I assumed "Ingest" was an app or a data format, like OwnTracks or GPX. I now realize it's just a verb. 😄

From this documentation, I also deduce that the tid and alt values, which the Home Assistent sends, are not used by Reitti? Is that a correct conclusion?

[dgraf-gh]

tid is not stored at all, alt is stored in the database and if your later would pull out the gpx from reitti, you would get that back. But it has no use for reitti. I was playing around with alt when introducing the new 3d map, but consumer gps (on your phone) is so bad, especially on altitude that it is of no use.

So, you can write something in them or leave them out. Both should work. One note about the endpoint.

It is better to use /api/v1/ingest/gpslogger endpoint instead of /api/v1/ingest/owntracks

You do not need the card return data from the owntracks endpoint. Everything else is the same.

And for security reasons, you propably want to send the token as a header instead of a url parameter. https://www.dedicatedcode.com/projects/reitti/4.0/api/

[ErikDB87]

And for security reasons, you propably want to send the token as a header instead of a url parameter. https://www.dedicatedcode.com/projects/reitti/4.0/api/

I don't think I'll use the API's for anything but communication on my home network, so I don't worry too much about security. But maybe I'll try it, for purism's sake 😉

[ErikDB87]

Let me know if this helped. If you figure it out we can add that also to the docs.

My suggestion for the docs would be to fold https://www.dedicatedcode.com/projects/reitti/4.0/api/ingest/ into https://www.dedicatedcode.com/projects/reitti/4.0/api/. Or to convert the latter to an overview page, listing the different sub-subjects. Now all the 'API' pages seem on the same level. (Of course it's on me to have investigated what 'ingest' just was...)

Also, https://www.dedicatedcode.com/projects/reitti/4.0/api/ingest/ mentions /api/v1/ingest/owntracks as endpoint, not /api/v1/ingest/gpslogger. Furthermore, it doesn't mention the header.

About the openHAB angle: an integration like with Home Assistant wouldn't really fit with how openHAB is structured. I'll just make a 'rule', which sends a HTTP POST request based on values that get updated.

[dgraf-gh]

Thanks for the feedback. I am actually right now in the change of the api docs for that part and the 5.0 release.

[dgraf-gh]

My suggestion for the docs would be to fold https://www.dedicatedcode.com/projects/reitti/4.0/api/ingest/ into https://www.dedicatedcode.com/projects/reitti/4.0/api/. Or to convert the latter to an overview page, listing the different sub-subjects. Now all the 'API' pages seem on the same level. (Of course it's on me to have investigated what 'ingest' just was...)

The theme is quite limited right now, I will probably add links with a short description what each endpoint does and can be used for into the API Overview page for the time.

About the openHAB angle: an integration like with Home Assistant wouldn't really fit with how openHAB is structured. I'll just make a 'rule', which sends a HTTP POST request based on values that get updated.

Do you mind in writing this down so I can add this to the documentation?

[dgraf-gh]

https://www.dedicatedcode.com/projects/reitti//5.0/api/

[ErikDB87]

Do you mind in writing this down so I can add this to the documentation?

If you want it mentioned, I would put it under "Scripting":

Scripting: Use bash scripts or other automation tools (a rule or script in openHAB) to import location data from various sources

It doesn't say much, but I don't think there's much to be said. :)

https://www.dedicatedcode.com/projects/reitti//5.0/api/

I would change this:

Instead of the token parameter, you can also use the X-API-Token header for enhanced security.

... to something like:

(For the API-TOKEN, see below, under Authentication.)

And there, I would start with something like:

There are two ways to include your API token as a query parameter:

Then the existing example, followed by a similar example, but obviously with the header option.