The PublicEarth API

PublicEarth allows the user to bookmark places from PublicEarth in his or her account, either to indicate a favorite place, or to build collections of places to share with a friend, use for planning a trip, or to simply stay organized. Saving places to a user’s account is very simple, the only requirement being the user be logged in using HTTP Basic authentication, or by using a three-legged OAuth key. Furthermore, calls to the saved places API are restricted to the user’s own account. You may not request information on any other user’s saved places except for the currently authenticated user.

Save a Place

To save a place, simply POST a place ID to the saved places URL:

POST http://api.publicearth.com/v2/saved.xml?id=xxxx-xxxxxx-xxxx-xxxxx

Note that you must POST the place’s internal GUID, not the slug!

After POSTing, you’ll receive the list of all the user’s saved places.

  <?xml version="1.0" encoding="UTF-8"?>
  <places total="17">
    <place id="b07b09b0-9e6a-11dd-b5ee">
    ...
    </place>
  </places>

Get the User’s Saved Places

Simply call the saved places URL with a standard GET request:

http://api.publicearth.com/v2/saved.xml

You’ll get the same results as you will saving a new place.

Remove a Saved Place

If the user would like to “unsave” a place, just delete the reference. Same as creating a saved place, but make an HTTP DELETE request:

DELETE http://api.publicearth.com/v2/saved.xml?id=xxxx-xxxxxx-xxxx-xxxxx

Collections

In order to keep a user’s growing list of saved places organized, those places may be grouped into collections. A collection is like an iTunes playlist.

Get a List of Collections

To request a list of the currently authenticated user’s collections:

GET http://api.publicearth.com/v2/collections.xml

  <collections total="3">
    <collection id="0fefcb52-e6c6-11de-9873-f34b25103489">
      <name>10 Places that Define Me</name>
      <slug>10-places-that-define-me</slug>
      <description>10 Places that Define Me</description>
    </collection>
    <collection id="10d06a54-e6c6-11de-9ab5-6f9c6abd4b1b">
      <name>Research: My Next Vacation</name>
      <slug>research-my-next-vacation</slug>
      <description>Research: My Next Vacation</description>
    </collection>
    <collection id="87348f0-e381-11de-asd4-b9234raue20d">
      <name>Monuments around Pearl Harbor</name>
      <slug>monuments-around-pearl-harbor</slug>
      <description></description>
    </collection>
  </collections>

Note that this will only return the authenticated user’s collections. List of other users’ collections are currently not available.

Places in a Collection

To get the list of places in a collection, provide the collection slug or ID:

GET http://api.publicearth.com/v2/collections/research-my-next-vacation.xml

  <collection id="87a41dd0-e381-11de-9f3f-b74bbef2e20d">
    <name>Monuments around Pearl Harbor</name>
    <slug>monuments-around-pearl-harbor</slug>
    <description></description>
    <places total="7">
      <place id="dd0fcde9-a50f-49bf-9cc1-0adf2c276fab">
        <name>Bow of the LST-480</name>
        <slug>bow-of-the-lst-480</slug>
        <url>http://www.publicearth.com/places/historic-site/bow-of-the-lst-480&lt;/url&gt;
        <category>historic-site</category>

     ...additional information removed for brevity...

    </places>  
  </collection>

In asking for places without specifying any other information, only places directly associated with a collection will be returned. PublicEarth also supports dynamic collections, whereby categories, sources, or other groups of information are associated with a collection. For example, a collection might be of hotels owned by the Marriott and restaurants. While users typically don’t create these types of collections themselves, they may exists. In order to request the places associated with these collections, a map bounding box must be provided:

GET http://api.publicearth.com/v2/collections/some-dynamic-collection.xml?swx=-105.250000&swy=40.040000&nex=-105.290000&ney=40.000000

This is basically a search, so pagination attributes are also supported:

GET http://api.publicearth.com/v2/collections/some-dynamic-collection.xml?swx=-105.250000&swy=40.040000&nex=-105.290000&ney=40.000000&limit=10&start=10

Create a Collection

To create a new collection for the current user, provide a name and optional description for the collection:

POST http://api.publicearth.com/v2/collections.xml?name=Sample+Collection&description=Some+description

Collections created will be associated with the currently authenticated user automatically.

Add Places to a Collection

Once the user has a collection, places may be added to it by putting them into the collection using the place ID:

PUT http://api.publicearth.com/v2/collections/monuments-around-pearl-harbor/places/dd0fcde9-a50f-49bf-9cc1-0adf2c276fab.xml

That will add the place with the ID of “dd0fcde9-a50f-49bf-9cc1-0adf2c276fab” to the user’s collection “monuments-around-pearl-harbor”. If the place is already in the collection, the request is ignored, i.e. the collections don’t support duplicate places.

Note that if you add a place to a collection that is not already in the user’s list of saved places, it will automatically be added to his or her saved places list.

Remove a Place From a Collection

To remove a place from a collection is the same call as adding a place, but use the HTTP DELETE method instead:

DELETE http://api.publicearth.com/v2/collections/monuments-around-pearl-harbor/places/dd0fcde9-a50f-49bf-9cc1-0adf2c276fab.xml

If the place is not in the collection, the request is simply ignored. Also, removing a place from a collection does not remove it from the user’s list of saved places.

Remove a Collection

To delete a collection, use the HTTP DELETE method with the collection ID.

DELETE http://api.publicearth.com/v2/collections/research-my-next-vacation.xml

The user may only delete collections belonging to him or her. Also, like removing a place from a collection, deleting a collection will not affect the user’s list of saved places.