Nearby Query

The querying of nearby objects is a way to find objects that are located near to a certain geographical point. The use of 'object' in a generic term that allows a network running a location service to return a list of specific object types depending of the servers capabilities.

The Buddycloud location server is compliant to the OSLO Protocol that defines how location objects can be shared across multiple open networks.

Nearby stanzas

Send a Nearby Query (by geographical point)
Send a Nearby Query (by reference point)
Send a Nearby Query (with options)

Send a Nearby Query (by geographical point)

The default nearby allows to you query nearby objects around a specific geographical point, all other options (discussed here) are set by the location server:

Client to server:

<iq to='butler.buddycloud.com' type='get' id='nearby1'>
    <query xmlns='urn:oslo:nearbyobjects'>
        <point lat='59.914' lon='10.73879' />
    </query>
</iq>

Server to client:

<iq from='butler.buddycloud.com' to='username@buddycloud.com' type='result' id='nearby1'>
    <query xmlns='urn:oslo:nearbyobjects'>
        <items>
            <item id='http://buddycloud.com/place/38473' var='place'>
                <name>Joe's Pizza Place</name>
                <description>Oslo, Norway</description>
                <distance>10</distance>                                         
 
                // Geolocation specific data
                <geoloc xmlns='http://jabber.org/protocol/geoloc'>
                    <locality>Oslo</locality>
                    <country>Norway</country>
                </geoloc>
 
                // Any extra place data: as applicable
                <x xmlns='http://buddycloud.com/place'>
                    <visibility>public</visibility>
                    <population>2</population>
                </x>
            </item>          
            <item id='http://buddycloud.com/place/94839' var='place'>
                <name>Murphys Irish Bar</name>
                <description>Oslo, Norway</description>
                <distance>25</distance>                                         
 
                // Geolocation specific data
                <geoloc xmlns='http://jabber.org/protocol/geoloc'>
                    <locality>Oslo</locality>
                    <country>Norway</country>
                    <lat>59.914</lat>
                    <lon>10.73879</lon>
                </geoloc>
 
                // Any extra place data: as applicable
                <x xmlns='http://buddycloud.com/place'>
                    <visibility>public</visibility>
                    <population>3</population>
                </x>
            </item>
            <item id='clive@buddycloud.com' var='person'>
                <name>Clive Cox</name>
                <description>looking forward to the weekend</description>
                <distance>50</distance>                                         
 
                // Geolocation specific data
                <geoloc xmlns='http://jabber.org/protocol/geoloc'>
                    <locality>Oslo</locality>
                    <country>Norway</country>
                </geoloc>
 
                // Any extra person data: as applicable
                <x xmlns='http://buddycloud.com/person'>
                    <thumbnail>http://buddycloud.com/people/24353/thumbtail.gif</thumbnail>
                </x>
            </item>
            <item id='travelinoslo@channels.buddycloud.com' var='channel'>
                <name>Travel in Oslo</name>
                <description>A great resource for travel trips in Oslo</description>
                <distance>150</distance>                                         
 
                // Geolocation specific data
                <geoloc xmlns='http://jabber.org/protocol/geoloc'>
                    <locality>Oslo</locality>
                    <country>Norway</country>
                </geoloc>
 
                // Any extra channel data: as applicable
                <x xmlns='http://buddycloud.com/channel'>
                    <rank>2848</rank>
                </x>
            </item>
       </items>
    </query>
</iq>

Send a Nearby Query (by reference point)

You can also perform a nearby query by using existing reference points, for example people or places. By using a reference point you don't necessarily need to know the geographical point referenced, which controls the privacy of the reference point in question.

Objects near a Person

Client to server:

<iq to='butler.buddycloud.com' type='get' id='nearby2'>
    <query xmlns='urn:oslo:nearbyobjects'>
        <reference type='person' id='marilyn@buddycloud.com'/>
    </query>
</iq>

Objects near a Place

Client to server:

<iq to='butler.buddycloud.com' type='get' id='nearby3'>
    <query xmlns='urn:oslo:nearbyobjects'>
        <reference type='place' id='http://buddycloud.com/places/3465'/>
    </query>
</iq>

Send a Nearby Query (with options)

Several options can be set when performing a nearby query.

By adding an <options /> element to the query, you can set optional result filters that are normall set by default on the server. You can limit the number of results returned for each requested object (i.e. limit of 5 returns 5 of each object). Set the nearby range of results to filter, then any object outside of that range is not included. Finally setting a since timestamp limits objects to ones that have have only been updated after this timestamp.

You can control which object types are returned in the query by adding a <request /> element for each object type you wish to return. Otherwise all object types are returned.

Client to server:

<iq to='butler.buddycloud.com' type='get' id='nearby4'>
    <query xmlns='urn:oslo:nearbyobjects'>
        <point lat='48.167222' lon='11.586111' /> 
        <options limit='10' range='5000' since='2009-02-14T17:58:35Z'/>
        <request var='place'/>
        <request var='person'/>
        <request var='image'/>
        <request var='wiki'/>
        <request var='channel'/>
    </query>
</iq>

Server to client:

<iq from='butler.buddycloud.com' to='username@buddycloud.com' type='result' id='nearby4'>
    <query xmlns='urn:oslo:nearbyobjects'>
        <items>
            <item id='http://buddycloud.com/places/767' var='place'>
                <name>Home</name>
                <description>Schwabing, Munich, Germany</description>
                <distance>10</distance> 
 
                // Geolocation specific data
                <geoloc xmlns='http://jabber.org/protocol/geoloc'>
                    <area>Schwabing</area>
                    <locality>Munich</locality>
                    <country>Germany</country>
                    <uri>http://buddycloud.com/places/767</uri>
                </geoloc>
 
                // Any extra place data: as applicable
                <x xmlns='http://buddycloud.com/place'>
                    <visibility>private</visibility>
                    <population>1</population>
                </x>
            </item>          
            <item id='http://www.panoramio.com/photo/28779' var='image'>
                <name>Artur-Kutscher-Platz</name>
                <description>von Westen gesehen</description>
                <distance>50</distance>
 
                // Geolocation specific data
                <geoloc xmlns='http://jabber.org/protocol/geoloc'>
                    <lat>48.167222</lat>
                    <lon>11.586111</lon>
                </geoloc>
 
                // Any extra wiki data: as applicable
                <x xmlns='http://buddycloud.com/image'>
                    <thumbnail>http://mw2.google.com/mw-panoramio/photos/square/28779.jpg</thumbnail>
                </x>
            </item>         
            <item id='simon@buddycloud.com' var='person'>
                <name>Simon Tennant</name>
                <description>likes to play the spoons</description>
                <distance>300</distance>
 
                // Geolocation specific data
                <geoloc xmlns='http://jabber.org/protocol/geoloc'>
                    <city>Schwabing</city>
                    <locality>Munich</locality>
                    <country>Germany</country>
                </geoloc>
 
                // Any extra person data: as applicable
                <x xmlns='http://buddycloud.com/person'>
                    <thumbnail>http://buddycloud.com/people/19/thumbtail.gif</thumbnail>
                </x>
            </item>        
            <item id='http://buddycloud.com/places/1198' var='place'>
                <name>Buddycloud Towers</name>
                <description>Schwabing, Munich, Germany</description>
                <distance>300</distance>                
 
                // Geolocation specific data
                <geoloc xmlns='http://jabber.org/protocol/geoloc'>
                    <street>Berlinerstr 18.</street>
                    <area>Schwabing</area>
                    <locality>Munich</locality>
                    <country>Germany</country>
                    <uri>http://buddycloud.com/places/1198</uri>
                </geoloc>
 
                // Any extra place data: as applicable
                <x xmlns='http://buddycloud.com/place'>
                    <visibility>public</visibility>
                    <category>residence</category>
                    <population>1</population>
                </x>
            </item>    
            <item id='http://en.wikipedia.org/wiki/M%C3%BCnchner_Freiheit' var='wiki'>
                <name>Münchner Freiheit</name>
                <description>The Münchner Freiheit (called Münchener Freiheit until 1998) is a square in Munich's Schwabing, near the English Garden.</description>
                <distance>400</distance>
 
                // Geolocation specific data
                <geoloc xmlns='http://jabber.org/protocol/geoloc'>
                    <lat>48.167548</lat>
                    <lon>11.586347</lon>
                </geoloc>
 
                // Any extra wiki data: as applicable
                <x xmlns='http://buddycloud.com/wiki'>
                    <thumbnail>http://en.wikipedia.org/wiki/Image:M%C3%BCnchner_Freiheit.jpg</thumbnail>
                </x>
            </item>
            <item id='schwabingdisco@channels.buddycloud.com' var='channel'>
                <name>Schwabing Disco</name>
                <description>For all disco lovers in Schwabing, Munich</description>
                <distance>500</distance>
 
                // Geolocation specific data
                <geoloc xmlns='http://jabber.org/protocol/geoloc'>
                    <area>Schwabing</area>
                    <locality>Munich</locality>
                    <country>Germany</country>
                    <lat>48.167364</lat>
                    <lon>11.586143</lon>
                </geoloc>
 
                // Any extra channel data: as applicable
                <x xmlns='http://buddycloud.com/channel'>
                    <population>21</population>
                    <rank>2839</rank>
                </x>
            </item>  
            <item id='helium@buddycloud.com' var='person'>
                <name>Helge Timenes</name>
                <description>has a story for every occasion</description>
                <distance>3834</distance>
 
                // Geolocation specific data
                <geoloc xmlns='http://jabber.org/protocol/geoloc'>
                    <area>Haidhausen</area>
                    <locality>Munich</locality>
                    <country>Germany</country>
                </geoloc>
            </item>
        </items>
    </query>
</iq>