location butler example of saving a place

Our implementation of the "Location Query" XMPP Protocol Extension (XEP) is not like any other server. It is in fact the first of its kind, the very first implementation of XEP-0255. On the other hand this is maybe not so surprising since XEP-0255 has been authored largely by us cloudheads. In any case, being the most senior component in the buddycloud hosehold we have given it the honorary working title "Location Butler".

Up until now, the Buddycloud Location Butler has been available to Buddycloud users only, but now we have decided to let it serve a larger audience. As of today, anyone can enrich their XMPP applications with location awareness by directing XEP-0255 conform stanzas to butler.buddycloud.com. In addition to geodetic (GPS) coordinates, the following location references are supported:

cell
wifi
bluetooth

For your convenience here are some examples:

<iq from='you@example.org' 
    to='butler.buddycloud.com' 
    id='023FE3AA1'
    type='get' 
    xml:lang='en-US'>
  <locationquery xmlns='urn:xmpp:locationquery:0'>
    <reference>
      <id>262:07:51047:50880</id> // Note: id = MCC:MNC:LAC:CID
      <type>cell</type>
      <signalstrength>-79</signalstrength>
    </reference>
  </locationquery>
</iq>

<iq from='you@example.org' 
    to='butler.buddycloud.com' 
    id='023FE3AA2'
    type='get' 
    xml:lang='en-US'>
  <locationquery xmlns='urn:xmpp:locationquery:0'>
    <reference>
      <id>00:1C:4A:D3:53:F8</id> // Note: id = MAC
      <type>wifi</type>
      <signalstrength>-70</signalstrength>
    </reference>
    <reference>
      <id>00:1B:2F:A6:A4:F2</id>
      <type>wifi</type>
      <signalstrength>-65</signalstrength>
    </reference>
  </locationquery>
</iq>

<iq from='you@example.org' 
    to='butler.buddycloud.com' 
    id='023FE3AA3'
    type='get' 
    xml:lang='en-US'>
  <locationquery xmlns='urn:xmpp:locationquery:0'>
    <lat>48.130605</lat>
    <lon>11.607284</lon>
    <accuracy>35.6</accuracy>
  </locationquery>
</iq>

<iq from='you@example.org' 
    to='butler.buddycloud.com' 
    id='023FE3AA4'
    type='get' 
    xml:lang='en-US'>
  <locationquery xmlns='urn:xmpp:locationquery:0'>
    <lat>48.130605</lat>
    <lon>11.607284</lon>
    <accuracy>35.6</accuracy>
    <reference>
      <id>262:07:51047:50880</id>
      <type>cell</type>
      <signalstrength>-79</signalstrength>
    </reference>
    <reference>
      <id>00:1C:4A:D3:53:F8</id>
      <type>wifi</type>
      <signalstrength>-70</signalstrength>
    </reference>
    <reference>
      <id>00:1B:2F:A6:A4:F2</id>
      <type>wifi</type>
      <signalstrength>-65</signalstrength>
    </reference>
    <reference>
      <id>00:09:5B:E8:7A:DA</id>
      <type>wifi</type>
      <signalstrength>-93</signalstrength>
    </reference>
    <reference>
      <id>00:21:FE:90:AA:28</id>
      <type>bluetooth</type>
    </reference>
  </locationquery>
</iq>

The results returned for queries like this will, as specified in the XEP, be in the form of a "geoloc" stanza.

Now, the Buddycloud Location Butler was not designed solely to handle XEP-0255 Location Queries. First and foremost it is a server for "social contextual location". What is social contextual location? Quite simple: A location labeled in a context that is meaningful to an individual or a group of people. For example "Home" is a location that is meaningful to you and anyone who knows where you live. "The Pub", "Work" "Ann's Parents' Place" etc are further examples. Assuming you have fed the Butler with enough location queries to give it a good idea of your location (the Buddycloud client sends a query every 3 minutes OR when Cell ID changes), all you need to do is to name it.

In the buddycloud terminology we refer to contextual locations simply as "places". The difference between places and locations using this definition is this: Location is continous while places are discrete. No matter where you are, you are always at a location, while you may or may not be at a place.

Here is an example of how to define a social contextual location, or place if you will:

<iq from='you@example.org' 
    to='butler.buddycloud.com' 
    id='023FE3AA5'
    type='set' 
    xml:lang='en-US'>
  <command xmlns='http://jabber.org/protocol/commands' node='location'>
    <x xmlns='jabber:x:data' type='form'>
      <field type='hidden' var='FORM_TYPE'>
        <value>buddycloud:location:set_current</value>
      </field>
      <field type='text-single' var='label'>
        <value>The Office</value>
      </field>
      <field type='boolean' var='store'>
        <value>true</value>
      </field>
    </x>
  </command>
</iq>

The location butler will then associate the specified label with your current location. When you some other time come back to this place, the text field of the location result will be "The Office". If you are only nearby this place, or just arrived there, the location buttler will reflect this too, e.g. "Near The Office".

If you want to supply more information, this will be used in the other fields of location query result when you are at this place:

<iq from='you@example.org' 
    to='butler.buddycloud.com' 
    id='023FE3AA6'
    type='set' 
    xml:lang='en-US'>
  <command xmlns='http://jabber.org/protocol/commands' node='location'>
    <x xmlns='jabber:x:data' type='form'>
      <field type='hidden' var='FORM_TYPE'>
        <value>buddycloud:location:set_current</value>
      </field>
      <field type='text-single' var='label'>
        <value>Starbucks Coffee</value>
      </field>
      <field type='boolean' var='public'>
        <value>true</value>
      </field>
      <field type='text-single' var='description'>
        <value>If you've seen one you've seen 'em all</value>
      </field>
      <field type='text-single' var='street'>
        <value>Unter den Linden 45</value>
      </field>
      <field type='text-single' var='area'>
        <value>Mitte</value>
      </field>
      <field type='text-single' var='city'>
        <value>Berlin</value>
      </field>
      <field type='text-single' var='postalcode'>
        <value>12345</value>
      </field>
      <field type='text-single' var='region'>
        <value>Berlin</value>
      </field>
      <field type='text-single' var='country'>
        <value>Germany</value>
      </field>
      <field type='text-single' var='latitude'>
        <value>58.447266</value>
      </field>
      <field type='text-single' var='longitude'>
        <value>28.168051</value>
      </field>
      <field type='text-single' var='wikiurl'>
        <value>http://en.wikipedia.org/wiki/Starbucks</value>
      </field>
      <field type='text-single' var='siteurl'>
        <value>http://starbucks.com</value>
      </field>
    </x>
  </command>
</iq>

NOTE: The public field, when set to true, specifies that the place shall be visible to and usable by other users.

For more place-management examples, see our API page.

For questions or bug reports, please send a quick e-mail to helge[at]buddycloud.com