the location engine plazes.net

  1. Introduction

  2. General Stuff
  3. Authentication
  4. Example Walkthrough

  5. Presence

  6. /presences (GET, POST)
  7. /presences/{id} (GET, PUT, DELETE)

  8. Plaze

  9. /plazes (GET, POST)
  10. /plazes/{id} (GET, PUT)
  11. /plazes/{id}/presences (GET)

  12. User

  13. /users (GET, POST)
  14. /users/{id} (GET, PUT, DELETE)
  15. /users/{id}/presence (GET)
  16. /users/{id}/presences (GET)
  17. /users/{id}/future_presences (GET)
  18. /users/{id}/past_presences (GET)
  19. Authenticated User: /me

Presences Collection

GET /presences

The collection of all presences within the site, ordered descending by created_at . Ordering by this field allows the same collection to be used as a news feed.

GET /presences.xml

200 OK
Content-type: application/xml 
<?xml version="1.0" encoding="UTF-8"?>
<presences type="array">
  <presence>
    <created_at type="datetime">2008-04-24T15:44:35Z</created_at>
    <device>plazer</device>
    <id type="integer">287322906</id>
    <plaze_id type="integer">645720854</plaze_id>
    <scheduled_at type="datetime">2008-04-24T16:44:35+01:00</scheduled_at>
    <status>Meh.</status>
    <updated_at type="datetime">2008-04-24T15:44:35Z</updated_at>
    <user_id type="integer">978752341</user_id>
  </presence>
  <presence>
    <created_at type="datetime">2008-04-24T15:44:35Z</created_at>
    <device nil="true"></device>
    <id type="integer">745747106</id>
    <plaze_id type="integer">615829812</plaze_id>
    <scheduled_at type="datetime">2008-05-15T18:44:35+01:00</scheduled_at>
    <status nil="true"></status>
    <updated_at type="datetime">2008-04-24T15:44:35Z</updated_at>
    <user_id type="integer">112643258</user_id>
  </presence>
  <presence>
    <created_at type="datetime">2008-04-24T15:44:35Z</created_at>
    <device nil="true"></device>
    <id type="integer">480703363</id>
    <plaze_id type="integer">622797944</plaze_id>
    <scheduled_at type="datetime">2008-01-02T19:00:00+03:00</scheduled_at>
    <status nil="true"></status>
    <updated_at type="datetime">2008-04-24T15:44:35Z</updated_at>
    <user_id type="integer">909918424</user_id>
  </presence>
  <presence>
    <created_at type="datetime">2008-04-24T15:44:35Z</created_at>
    <device nil="true"></device>
    <id type="integer">277199378</id>
    <plaze_id type="integer">645720854</plaze_id>
    <scheduled_at type="datetime">2008-04-24T16:44:35+01:00</scheduled_at>
    <status nil="true"></status>
    <updated_at type="datetime">2008-04-24T15:44:35Z</updated_at>
...

POST /presences

Create a new presence. See Presences for complete field list.

Every presence must have a plaze. The plaze can be specified explicitly by including an existing plaze_id as attribute of the presence in the create request. Example:

POST /presences.xml

Content-type: application/x-www-form-urlencoded

presence[plaze_id]=87873

201 Created
Content-type: application/xml
Location: http://plazes.net/presences/81449838 
<?xml version="1.0" encoding="UTF-8"?>
<presence>
  <created_at type="datetime">2008-04-25T20:26:03Z</created_at>
  <device nil="true"></device>
  <id type="integer">81449838</id>
  <plaze_id type="integer">645720854</plaze_id>
  <scheduled_at type="datetime">2008-04-25T21:26:03+01:00</scheduled_at>
  <status nil="true"></status>
  <updated_at type="datetime">2008-04-25T20:26:03Z</updated_at>
  <user_id type="integer">978752341</user_id>
  <plaze>
    <address nil="true"></address>
    <category>office</category>
    <city>London</city>
    <country_code>GB</country_code>
    <created_at type="datetime">2008-04-24T16:05:53Z</created_at>
    <id type="integer">645720854</id>
    <name>The Basement</name>
    <state nil="true"></state>
    <timezone>Europe/London</timezone>
    <updated_at type="datetime">2008-04-24T16:05:53Z</updated_at>
    <zip_code nil="true"></zip_code>
    <latitude type="float">51.509525525099</latitude>
    <longitude type="float">-0.134676861410192</longitude>
    <country>United Kingdom</country>
  </plaze>
</presence>

The plaze can also be specified by including a plaze element with attributes inside the presence. This will trigger a search and will use the first best match as plaze of the presence ('feeling-lucky-mode'). If none found, it will create a new plaze if sufficient data was given. If neither lookup nor plaze creation succeeds then the presence creation will fail. Example:

POST /presences.xml

Content-type: application/xml

<presence>
    <status>Pretending to work</status>
    <plaze>
      <q>basement</q>
    </plaze>
  </presence>
201 Created
Content-type: application/xml
Location: http://plazes.net/presences/81449828 
<?xml version="1.0" encoding="UTF-8"?>
<presence>
  <created_at type="datetime">2008-04-24T15:54:50Z</created_at>
  <device nil="true"></device>
  <id type="integer">81449828</id>
  <plaze_id type="integer">645720854</plaze_id>
  <scheduled_at type="datetime">2008-04-24T16:54:50+01:00</scheduled_at>
  <status>Pretending to work</status>
  <updated_at type="datetime">2008-04-24T15:54:50Z</updated_at>
  <user_id type="integer">978752341</user_id>
  <plaze>
    <address nil="true"></address>
    <category>office</category>
    <city>London</city>
    <country_code>GB</country_code>
    <created_at type="datetime">2008-04-24T15:44:34Z</created_at>
    <id type="integer">645720854</id>
    <name>The Basement</name>
    <state nil="true"></state>
    <timezone>Europe/London</timezone>
    <updated_at type="datetime">2008-04-24T15:44:34Z</updated_at>
    <zip_code nil="true"></zip_code>
    <latitude type="float">51.509525525099</latitude>
    <longitude type="float">-0.134676861410192</longitude>
    <country>United Kingdom</country>
  </plaze>
</presence>

The attributes inside the plaze element are the same as those for the plaze search at GET /plazes

Creating a presence for a known plaze, tagging it with the mac_address to improve later plaze searches:

POST /presences.xml

Content-type: application/x-www-form-urlencoded

presence[networks][][mac_address]=00:00:00:00:00:01&presence[plaze_id]=615829812&presence[status]=Checking in to a known plaze

201 Created
Content-type: application/xml
Location: http://plazes.net/presences/81449839 
<?xml version="1.0" encoding="UTF-8"?>
<presence>
  <created_at type="datetime">2008-04-25T20:45:58Z</created_at>
  <device nil="true"></device>
  <id type="integer">81449839</id>
  <plaze_id type="integer">615829812</plaze_id>
  <scheduled_at type="datetime">2008-04-25T21:45:58+01:00</scheduled_at>
  <status>Checking in to a known plaze</status>
  <updated_at type="datetime">2008-04-25T20:45:58Z</updated_at>
  <user_id type="integer">978752341</user_id>
  <plaze>
    <address nil="true"></address>
    <category>theater</category>
    <city>London</city>
    <country_code>GB</country_code>
    <created_at type="datetime">2008-04-24T16:05:53Z</created_at>
    <id type="integer">615829812</id>
    <name>The London Opera</name>
    <state nil="true"></state>
    <timezone>Europe/London</timezone>
    <updated_at type="datetime">2008-04-24T16:05:53Z</updated_at>
    <zip_code nil="true"></zip_code>
    <latitude type="float">51.65</latitude>
    <longitude type="float">-0.14</longitude>
    <country>United Kingdom</country>
  </plaze>
</presence>

See Networks for more on storing networks with presences.

Creating a presence without knowing the plaze but with a mac_address :

POST /presences.xml

Content-type: application/xml

<presence>
    <networks type="array">
      <network>
        <mac_address>00:00:00:00:00:aa</mac_address>
      </network>
    </networks>
  </presence>
201 Created
Content-type: application/xml
Location: http://plazes.net/presences/81449830 
<?xml version="1.0" encoding="UTF-8"?>
<presence>
  <created_at type="datetime">2008-04-24T15:54:52Z</created_at>
  <device nil="true"></device>
  <id type="integer">81449830</id>
  <plaze_id type="integer">645720854</plaze_id>
  <scheduled_at type="datetime">2008-04-24T16:54:52+01:00</scheduled_at>
  <status nil="true"></status>
  <updated_at type="datetime">2008-04-24T15:54:52Z</updated_at>
  <user_id type="integer">978752341</user_id>
  <plaze>
    <address nil="true"></address>
    <category>office</category>
    <city>London</city>
    <country_code>GB</country_code>
    <created_at type="datetime">2008-04-24T15:44:34Z</created_at>
    <id type="integer">645720854</id>
    <name>The Basement</name>
    <state nil="true"></state>
    <timezone>Europe/London</timezone>
    <updated_at type="datetime">2008-04-24T15:44:34Z</updated_at>
    <zip_code nil="true"></zip_code>
    <latitude type="float">51.509525525099</latitude>
    <longitude type="float">-0.134676861410192</longitude>
    <country>United Kingdom</country>
  </plaze>
</presence>

Creating a presence for a known plaze with the results from a WLAN scanner:

POST /presences.xml

Content-type: application/x-www-form-urlencoded

presence[networks][][essid]=FON_AP&presence[networks][][essid]=foobar wlan&presence[networks][][essid]=NETGEAR uncofigured router&presence[plaze_id]=615829812&presence[status]=Checking in to a known plaze

201 Created
Content-type: application/xml
Location: http://plazes.net/presences/81449840 
<?xml version="1.0" encoding="UTF-8"?>
<presence>
  <created_at type="datetime">2008-04-25T20:46:45Z</created_at>
  <device nil="true"></device>
  <id type="integer">81449840</id>
  <plaze_id type="integer">615829812</plaze_id>
  <scheduled_at type="datetime">2008-04-25T21:46:45+01:00</scheduled_at>
  <status>Checking in to a known plaze</status>
  <updated_at type="datetime">2008-04-25T20:46:45Z</updated_at>
  <user_id type="integer">978752341</user_id>
  <plaze>
    <address nil="true"></address>
    <category>theater</category>
    <city>London</city>
    <country_code>GB</country_code>
    <created_at type="datetime">2008-04-24T16:05:53Z</created_at>
    <id type="integer">615829812</id>
    <name>The London Opera</name>
    <state nil="true"></state>
    <timezone>Europe/London</timezone>
    <updated_at type="datetime">2008-04-24T16:05:53Z</updated_at>
    <zip_code nil="true"></zip_code>
    <latitude type="float">51.65</latitude>
    <longitude type="float">-0.14</longitude>
    <country>United Kingdom</country>
  </plaze>
</presence>

Failures

If the Presence could not be created, because a required field is missing or malformed an error 422 is returned.

POST /presences.xml

Content-type: application/x-www-form-urlencoded

422 Unprocessable Entity
Content-type: application/xml 
<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Plaze can't be blank</error>
  <error>Plaze could not be found</error>
</errors>

© 2008 plazes AG