Skip to content
Daniel Kirstenpfad edited this page Mar 13, 2014 · 15 revisions

Welcome to the Miataru - 見当たる wiki!

This wiki will include all old and new versions of the miataru protocol specification. It's meant to be a place for comment and discussion.

Why Miataru?

When Google closed it’s Latitude service it suddenly became apparent to me how much I used that service and how many processes in daily live are already relying on the location of persons.

I can give 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 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.

What is it supposed to be?

Miataru is:

  • Server
    • 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 lost
    • 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 (BSD license, free-for-all) – the protocol itself will be documented so that any self-written server can be used as well
  • Client
    • The client software is preferably installed on a mobile device like an iPhone or an Android phone. It’s constantly recording and reporting location updates, configurable to the likings of the user. The main featureset of a mobile client is:
    • Runs continuously and reports locations to the Miataru server depending on the following different strategy patterns to save power on a mobile device.
    • The client software can also be a browser client / html5 application.
    • The Client User Interface is as simple as possible and allows the user to manage a list of other devices he can display on a map view as well as all the basic configuration steps.
    • A first-run set-up is included so a new user can immediately start using the service → a pre-defined Miataru server is available in the UI

the Miataru protocol specification

To report and retrieve location data a very simple protocol is being used. This protocol transports JSON formatted data using HTTP / HTTPS. So do not forget to set the Content-Type to "application/json" when doing requests towards the Miataru server.


The Miataru Protocol is versioned using a custom URL scheme. So each supported version will be reachable through it’s own version URL. For example:

This would address version 1 of the GetLocation method on the service URL.

When there are new versions coming up they can be accessed changing the /v1/ part to the respective version string.

Each version will be subject to an extra chapter in this document and a new version is based upon the previous version. So all unchanged methods might not be described in addition.