Introduction

Querying servers for nearby objects.

Details

Recommended: Privacy and protection of private data is paramount, so server-to-server queries should be carried out over a secure connection

Feature Discovery

One location server queries another federated location server to discover the nearby features for the called server.

<iq from='location.aka-aki.com' to='nearby.buddycloud.com' type='get'>
    <query xmlns='urn:oslo:nearbyobjects#disco' />
</iq>

Server responds successfully with a list of available features.

<iq from='nearby.buddycloud.com' to='location.aka-aki.com' type='result'>
    <query xmlns='urn:oslo:nearbyobjects#disco'>
        <feature var='place' />
        <feature var='person' />
        <feature var='channel' />
    </query>
</iq>

Nearby Object Query

Example 1: Using default options (server specific) and all available objects.

Server requests nearby objects from federated location server

<iq to='nearby.rummble.com' from='nearby.buddycloud.com' type='get'>
    <query xmlns='urn:oslo:nearbyobjects'>
        <point lat='59.914' lon='10.73879' />				        // Required
    </query>
</iq>

Other server responds with nearby objects

<iq to='nearby.buddycloud.com' from='nearby.rummble.com' type='result'>
    <query xmlns='urn:oslo:nearbyobjects'>
        <items>
            <item id='http://rummble.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='urn:oslo:nearbyobjects:rummble#place'>
                    <visibility>public</visibility>
                    <population>2</population>
                </x>
            </item>          
            <item id='http://rummble.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='urn:oslo:nearbyobjects:rummble#place'>
                    <visibility>public</visibility>
                    <population>3</population>
                </x>
            </item>
            <item id='clive@rummble.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='urn:oslo:nearbyobjects:rummble#person'>
                    <thumbnail>http://rummble.com/people/24353/thumbtail.gif</thumbnail>
                </x>
            </item>
       </items>
    </query>
</iq>

Example 2: Server uses optional data to control result data

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

Nearby objects are returned

<iq to='nearby.rummble.com' from='nearby.buddycloud.com' type='result'>
    <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='urn:oslo:nearbyobjects:buddycloud#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='urn:oslo:nearbyobjects:buddycloud#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='urn:oslo:nearbyobjects:buddycloud#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='urn:oslo:nearbyobjects:buddycloud#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='urn:oslo:nearbyobjects:buddycloud#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='urn:oslo:nearbyobjects:buddycloud#channel'>
                    <population>21</population>
                </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>