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

Plazes Collection

GET /plazes

Finding the right Plaze is the first step to start for many uses of the API. To create a Presence, you must either find a Plaze or let the feeling-lucky mode of Presence creation find one for you.

The collection of Plazes is ordered on relevancy to the search query, the personal history of the authenticated user, and general interestingness of the plaze. So for example a search for q=home returns many plazes, but the plaze that the user already has a presence at will be sorted first.

When multiple query parameters are combined, only plazes that match all parameters are returned.

Query parameters:

q
The textual terms to search for in the following fields: name, address, zip_code, city, state (and full state name), country_code (and country names) category, tags
near
A point. Searches plazes near this point and sorts them by distance. The results are not strictly sorted by distance but may be slightly reordered depending on their relevancy
accuracy
Distance in meters around the point given in near. Plazes within that range are weighed only by other relevance factors, not by their distance to the point. Defaults to 100 meters.
bounds[sw], bounds[ne]
The south west and the north east corner point of a rectangular area. Only plazes within this area will be returned
networks
A list of key value pairs describing network ids at that plaze

Example with text query:

GET /plazes.xml ? q=opera

200 OK
Content-type: application/xml 
<?xml version="1.0" encoding="UTF-8"?>
<plazes type="array">
  <plaze>
    <address nil="true"></address>
    <category>theater</category>
    <city>London</city>
    <country_code>GB</country_code>
    <created_at type="datetime">2008-04-24T15:44:34Z</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-24T15:44:34Z</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>
</plazes>

Example with a point near and a text query:

GET /plazes.xml ? near=47.645730,-122.309246&q=shop

200 OK
Content-type: application/xml 
<?xml version="1.0" encoding="UTF-8"?>
<plazes type="array">
  <plaze>
    <address nil="true"></address>
    <category>shop</category>
    <city>Bellevue</city>
    <country_code>US</country_code>
    <created_at type="datetime">2008-04-24T16:05:53Z</created_at>
    <id type="integer">7105771</id>
    <name>Bellevue Square Gardens</name>
    <state nil="true"></state>
    <timezone>America/Juneau</timezone>
    <updated_at type="datetime">2008-04-24T16:07:00Z</updated_at>
    <zip_code nil="true"></zip_code>
    <latitude type="float">47.618043</latitude>
    <longitude type="float">-122.201217</longitude>
    <country>United States</country>
  </plaze>
</plazes>

Example with a mac_address:

GET /plazes.xml ? networks[][mac_address]=00:00:00:00:00:aa

200 OK
Content-type: application/xml 
<?xml version="1.0" encoding="UTF-8"?>
<plazes type="array">
  <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>
</plazes>

If no results are found, an empty collection is returned

GET /plazes.xml ? q=cannotfindthis

200 OK
Content-type: application/xml 
<?xml version="1.0" encoding="UTF-8"?>
<plazes type="array"/>

POST /plazes

Create a new Plaze. See Plaze for complete field list.

Please try to find if the desired Plaze already exists before creating a new one, with GET /plazes

Creating a Plaze requires a name, city and country at a minimum. When latitude and longitude are not included, they will be geocoded from the address.

POST /plazes.xml

Content-type: application/xml

<plaze>
    <name>The White House</name>
    <city>Washington</city>
    <country_code>US</country_code>
    <address>1600 Pennsylvania Avenue NW</address>
  </plaze>
201 Created
Content-type: application/xml
Location: http://plazes.net/plazes/645720855 
<?xml version="1.0" encoding="UTF-8"?>
<plaze>
  <address>1600 Pennsylvania Avenue NW</address>
  <category>other</category>
  <city>Washington</city>
  <country_code>US</country_code>
  <created_at type="datetime">2008-04-24T15:51:12Z</created_at>
  <id type="integer">645720855</id>
  <name>The White House</name>
  <state nil="true"></state>
  <timezone>America/Chicago</timezone>
  <updated_at type="datetime">2008-04-24T15:51:12Z</updated_at>
  <zip_code nil="true"></zip_code>
  <latitude type="float">38.8987242542956</latitude>
  <longitude type="float">-77.0373744084103</longitude>
  <country>United States</country>
</plaze>

If the Plaze could not be created because there is some missing information such as city or country_code 422 will be returned:

POST /plazes.xml

Content-type: application/xml

<plaze>
    <name>Fantasia</name>
  </plaze>
422 Unprocessable Entity
Content-type: application/xml 
<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Country code can't be blank</error>
  <error>Country code is not known by us</error>
  <error>City can't be blank</error>
</errors>

© 2008 plazes AG