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:
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:
For further information please refer to the next tabs on this website, the specification wiki or the specification pdf file.
The Miataru Android App is under development. You can access the source-code repository here.
There's no public release yet.
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:
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.
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.
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.
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.
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.
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:
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.