Miataru - be found

OpenSource location tracking.

Miataru or 見当たる is Japanese and means "be found" or "to come across" and it's meant to be a set of tools to allow the user to track locations and choose how to work with the data as well as how data is stored if at all.

When Google closed it’s Latitude service it suddenly became apparent how many processes in an home automation system and daily life already make use of the ability to locate devices.

Some examples:

  • Being able to tell where family members are right now helps a lot when organizing your day and work – it minimizes communication overhead a lot. How many times did you call people “where are you now?”
  • It’s a blessing in home automation to have that meta data to control systems. Think of your house knowing you are approaching and therefore increases the heating on it’s own so it’s warm when you arrive or it lowers the heating while you are away?
  • Proximity Alerts help to avoid surprises (for all those who don’t like them)
  • Knowing the metrics of your day, week, month, year makes a lot of sense when you think about lowering transportation costs and personal energy consumption
  • You’re a photographer and you want to geo-tag your pictures after the shooting or you found a nice spot and you want to find it again in the future?

Miataru is being built to fill those and more use cases around the location of devices with the simple twist that the user always can decide what happens to the data and when.

The Miataru toolset contains:

  • OpenSource Server (a publicly available demo instance for limited usage included)
  • fully documented Server API
  • Client Applications (planned right now for iOS, Android and Web)

For further information please refer to the next tabs on this website, the specification wiki or the specification pdf file.

iOS App

The Miataru iOS app is available in the iOS AppStore. Click on the below badge to download it!

Android App

The Miataru Android App is under development. You can access the source-code repository here.

There's no public release yet.

HTML5 WebClient Application

The HTML5 Webclient Application is currently under development. The current work-in-progress state can be viewed here:

You can also embed it anywhere you want:

SailfishOS Client

Dr. Andreas Heil took on the task of creating an SailfishOS version of the Miataru client. You can get the current code here:


The reference Implementation of the Miataru server is done using Node.JS and Redis and will be released as under the 2-clause BSD license. Find more information and a download link at the GitHub pages.

Current Build Status:

  • A server that stores location data (sent in using JSON and a HTTP POST request) for a given amount of seconds
  • After the pre-configured amount of seconds the location data for a user is "forgotten"
  • A server that makes available a given amount of location history, if the user wants that (not by default)
  • A server that offers through simple GET requests the location of a particular device and eventually a location history of configurable length/duration
  • The server component will be released as open source software – the protocol itself will be documented so that any self-written server can be used as well

The Miataru API is very simple and straight forward. Generally you're posting (HTTP POST) a JSON formatted request to a service method locations and you get back a JSON formatted answer.

If you prefer a more interactive version of this API documentation please refer to the SWAGGER based API specification here.

Please take into consideration that this has the request-for-comment status and that it can change while there's work done on client and server applications. Versioning therefore is done by prepending the version number - /v1/ for version 1 - to the method call.

/v1/UpdateLocation

This method is used to update the location of a device. The device does not need to be known already to the Miataru server but it rather creates a unique identifier for itself in the client application. This unique identifier, or device ID is then used to address this particular device.

Example:

{
    "MiataruConfig": {
        "EnableLocationHistory": "False",
        "LocationDataRetentionTime": "15"
    },
    "MiataruLocation": [
        {
            "Device": "7b8e6e0ee5296db345162dc2ef652c1350761823",
            "Timestamp": "1376735651302",
            "Longitude": "10.837502",
            "Latitude": "49.828925",
            "HorizontalAccuracy": "50.00"
        }
    ]
}
				

The data structure allows to post multiple location updates in one request, even for multiple devices.

The server will response with a simple response message:

{
	"MiataruResponse":"ACK", 
	"MiataruVerboseResponse":"><)))x>"
}
				

The response can be ACK or NACK - if there's a NACK you got a more verbose error description in the MiataruVerboseResponse field. If it's ACK you got a nice fish there.


/v1/GetLocation

To retrieve a specific devices latest known location the /GetLocation method is used. Please note that the MiataruConfig portion is optional. RequestMiataruDeviceID should be the ID of the device the request is sent from (or an identifier like an URL).

Example Request:

{
    "MiataruConfig": 
    {
        "RequestMiataruDeviceID": "6140c3c0-4a7d-40d2-99ab-39414cac3509"
    },
    "MiataruGetLocation": [
        {
            "Device": "7b8e6e0ee5296db345162dc2ef652c1350761823"
        }
    ]
}
				

By adding more devices to the array you get the locations of multiple devices in one request.

Example Response:

{
    "MiataruLocation": [
        {
            "Device": "7b8e6e0ee5296db345162dc2ef652c1350761823",
            "Timestamp": "1376735651302",
            "Longitude": "10.837502",
            "Latitude": "49.828925",
            "HorizontalAccuracy": "50.00"
        }
    ]
}
				

If there's no known location data for a device the server will report back with a filled MiataruNoLocation array.


/v1/GetLocationHistory

Location History is stored on the server only if the client told the server to do so using the “EnableLocationHistory” setting in the Location Update requests. For transitions of enabling/disabling that functionality: Everytime a Location Update is received by the server with “EnableLocationHistory=false” the server removes all stored Location History till that point.

There is a server-side setting that controls up to how many Location Updates the server is storing in the Location History before it removes the oldest one.

To request the Location History of a particular device the client sends the following POST request to the GetLocationHistory service URL. Please note that the MiataruConfig portion is optional. RequestMiataruDeviceID should be the ID of the device the request is sent from (or an identifier like an URL).

Example Request:

{   "MiataruConfig": 
    {
        "RequestMiataruDeviceID": "6140c3c0-4a7d-40d2-99ab-39414cac3509"
    },
    "MiataruGetLocationHistory": {
        "Device": "7b8e6e0ee5296db345162dc2ef652c1350761823",
        "Amount": "25"
    }
}
				

The server will answer back with an Array of LocationUpdates if there are Location Updates, or a List of NoLocations when there are none. If the client requested more Location Updates than there are available the server will return those available.

Example Response:

{
    "MiataruServerConfig": {
        "MaximumNumberOfLocationUpdates": "1000",
        "AvailableDeviceLocationUpdates": "25"
    },
    "MiataruLocation": [
        {
            "Device": "7b8e6e0ee5296db345162dc2ef652c1350761823",
            "Timestamp": "1376735651302",
            "Longitude": "10.837502",
            "Latitude": "49.828925",
            "HorizontalAccuracy": "50.00"
        },
        {
            "Device": "7b8e6e0ee5296db345162dc2ef652c1350761823",
            "Timestamp": "1376737022853",
            "Longitude": "10.937502",
            "Latitude": "49.858925",
            "HorizontalAccuracy": "5.00"
        }
    ]
}				
				

If there's no known location data for a device the server will report back with a MiataruNoLocation array instead of a MiataruLocation array.


/v1/GetVisitorHistory

Visitor History is stored on the server with every request to the location or location history information of a device.

There is a server-side setting that controls up to how many Visitors the server is storing in the Visitor History before it removes the oldest one.

To request the Visitor History of a particular device the client sends the following POST request to the GetVisitorHistory service URL.

Example Request:

{
    "MiataruGetVisitorHistory": {
        "Device": "7b8e6e0ee5296db345162dc2ef652c1350761823",
        "Amount": "25"
    }
}
				

The server will answer back with an Array of MiataruVisitors if there are Visitors, or an empty list when there are none. If the client requested more Visitor Updates than there are available the server will return those available.

Example Response:

{
    "MiataruServerConfig": {
        "MaximumNumberOfVisitorHistory": "10",
        "AvailableVisitorHistory": "2"
    },
    "MiataruVisitors": [
        {
            "DeviceID": "7b8e6e0ee5296db345162dc2ef652c1350761823",
            "TimeStamp": "1437683462"
        },
        {
            "DeviceID": "7b8e6e0ee5296db345162dc2ef652c1350761823",
            "TimeStamp": "1437683462"
        }
    ]
}				
				

If there's no known location data for a device the server will report back with a MiataruNoLocation array instead of a MiataruLocation array.

Miataru is an open source project and like most open source projects it depends on the contributions by passionate developers out there. If you want to take part in the development process feel free to contact us or send in pull requests.

Contacting us works best using these methods:

  • send an eMail to contact@miataru.com
  • tweet a tweet to @bietiekay
  • open an issue on GitHub

On purpose we are using a widely accepted open source license that allows you to do whatever you like with the source code as long as you refer to the original creators of it.