Help: API People

Active / Passive

MLC supports (if you paid for the unlocked version) people as APIs in an active and passive way. This way you can use any app or service on any device you like to get your location into the app instead of using the built-in method. An actively used API is one that the MLC server calls actively every 5 minutes. A passively used API is one that calls the MLC server itself.

Examples of actively used APIs are:

  • Any server where your location can be obtained using a HTTP(S) request

Examples of passively used APIs are:

Examples

Below, there are some examples from services I know. Feel free to ask how it works for your particular service or try and report to me how it is working for you.

Actively used APIs

For actively used APIs you need to make sure your location details are up to date and visible on your server by HTTP(S) requests. I don't currently support authentication, however, most servers allow the authentication details to be passed using the URL.

Passively used APIs

Passively used APIs are usually in the form of an app that pushes GPS data to a server.

Home Assistant

To use a device tracker from Home Assistant to update an API person in a group you will need to do the following:

First, you need to have a working device tracker in home assistant where you push the GPS coordinates to. Check that you can see the coordinates in the attributes of the device_tracker you want to use.

First, let's do some setup in the MLC app.

Go to the group you want to add the API person, press the red button and "Add a person to this group using an API".

Choose a picture and a name.

Set the first two settings to "Passive" and "URL".

Fill in the attribute names "latitude" and "longitude".

Press "Test" and copy the URL. Save afterwards.

Create a new rest_command like this with your URL:

rest_command:
update_mlc:
url: "https://us-central1-jrclockwidget.cloudfunctions.net/submitLocation?group=XXXXXX&person=XXXXXX&latitude={{ state_attr('device_tracker.YOUR_DEVICE_TRACKER', 'latitude') }}&longitude={{ state_attr('device_tracker.YOUR_DEVICE_TRACKER', 'longitude') }}"

Now you can configure Home Assistant to run this RESTful command whenever you like. My suggestion is to call it whenever the latitude or longitude of the device tracker changes to get the most up-to-date information to MLC.
This automation would look something like this (in YAML):
alias: Update MLC Location
description: ''
trigger:
- platform: state
entity_id: device_tracker.YOUR_DEVICE_TRACKER
attribute: latitude
- platform: state
entity_id: device_tracker.YOUR_DEVICE_TRACKER
attribute: longitude
condition: []
action:
- service: rest_command.update_mlc
data: {}

GPSLogger

To use GPSLogger to send your GPS data to MLC, you first need to set up a person in the MLC app.

Go to the group you want to add the API person, press the red button and "Add a person to this group using an API".

Choose a picture and a name.

Set the first two settings to "Passive" and "URL".

Fill in the attribute names "latitude" and "longitude".

Press "create", select and copy the URL given and press "create" again.

Next, go to the GPSLogger app, so to the side (hamburger) menu and press "Logging details".

Press, "Log to custom URL".

In the URL field, paste the URL you copied and replace "{ LATITUDE }" with "%LAT" and "{ LONGITUDE }" with "%LON".

Go back and "Start Logging"!

Overland GPS Tracking

To use Overland to send your GPS data to MLC, you first need to set up a person in the MLC app.

Go to the group you want to add the API person, press the red button and "Add a person to this group using an API".

Choose a picture and a name.

Set the first two settings to "Passive" and "JSON".

Fill in the attribute names latidude: "$.locations[-1:]..coordinates[0]" and longitude: "$.locations[-1:]..coordinates[1]".

Press "create", select and copy the URL given and press "create" again.

Next, go to the Overland app and go to "Settings".

In "Receiver Endpoint" paste the URL you copied.

Set-up the rest of the settings, turn on Overland and you're done!