API Documentation

Please note: This is pre-release documentation, and the API is subject to change.

Also, for questions related to the API, please join the amidst Google Group and ask there.

• Introduction
• Basic Concepts
  • Endpoint
  • Licenses
  • Authentication
  • HTTP Requests
  • HTTP Status Codes
  • Encoding
  • Tokens
  • Response Format
  • Forms
  • Client Expectations
  • Place Marks
• Methods
  • auth/login
  • auth/logout
  • contacts/add
  • people/[username]/network
  • people/[username]/places/tags/[tags]
  • people/[username]/reviews
  • places/add
  • places/countries
  • places/[place id]
  • places/[place id]/vote
  • places/[place id]/mark
  • places/tags/[tags]
  • notes/note_place/[place id]
  • notes/[note id]/edit
  • notes/[note id]/delete
  • search/people
  • search/places

Introduction

We expose some of this site's functionality through an Application Programming Interface (API). This document describes that API, and is meant as a guide for people wishing to build applications on top of the functionality we provide in this site.

Basic Concepts

Endpoint

The current endpoint for the API is http://amid.st/api/. This is the location relative to which all API requests must be submitted.

Licenses

We're still working out the legal issues surrounding data retrieved from the API.

Authentication

Authentication in the API is currently session-based. This means that your client must be capable of communication over HTTP, as well as have a storage mechanism for cookies which persists across requests. Session data storage is minimal, however, as we strive to be pragmatically RESTful.

If you are not authenticated, and try to perform an action which requires authentication, you will be redirected to auth/login, which will return a response containing an element like this:

<logged-in status="no"></logged-in>

Possible values of status are "yes" and "no".

HTTP Requests

In general, API requests which do not modify data use HTTP GET requests. API requests which modify, update, or delete data use HTTP POST requests. Request parameters should be encoded in UTF-8, as that is the only encoding we accept.

HTTP Status Codes

We endeavor to return appropriate status codes for each request. Here's what you're likely to receive from us:

• 200 OK: Everything worked.
• 400 Bad Request: Request format error.
• 401 Not Authorized: Authentication credentials needed, or invalid.
• 403 Forbidden: We understand, but refuse to fulfill, your request. Used for the rate limit being exceeded.
• 404 Not Found: The resource you're looking for doesn't exist.
• 500 Internal Server Error: Our bad. Please report it to us.
• 502 Bad Gateway: Service is down.
• 503 Service Unavailable: Service is up but too busy.

Encoding

All requests and responses should be encoded in UTF-8. Submitting data in non-UTF-8 encodings will result in your data being mangled upon response, mangled for other users, or our system rejecting your request.

Tokens

In order to prevent unauthorized third party modifications to your data, we've implemented a token system. Each login session has an associated token, which is submitted with each form and validated against the token we have stored for your session.

For example, the auth/logout method requires a token in order to log you out. The token is passed as a query parameter (?token=[your token]), and you will not be logged out of your session unless the token matches the token assigned to your session. If we were to simply log you out when you visited auth/logout, a third party site could potentially log you out just by causing you to visit auth/logout. The rationale behind having tokens on form submissions is similar, and protects against very similar types of attacks.

Response Format

The general response format looks like this:

<response version="1.0">
<request path="[path to method]"/>
[method-specific response information]
</response>

The version attribute is important. If it changes, you can expect the API to have changed, and you should refer to this document, which will have information on the changes.

Forms

In order to describe the interface a query expects, we output a simple description of what the input parameters are upon a GET request to that method URL:

<?xml version="1.0" encoding="utf-8"?>
<response version="1.0">
    <request path="/api/notes/note_place/1057"></request>
    <form>
        <input hidden="yes" required="no" name="token" value="efa471da135ea7a6ff3bc18a12751dc36411cd22"></input>
        <input hidden="yes" required="yes" name="place_id" value="1057"></input>
        <input hidden="yes" required="no" name="rating_cancel" value="true"></input>
        <input hidden="no" required="yes" name="rating"></input>
        <input hidden="no" required="no" name="notes"></input>
        <input hidden="yes" required="no" name="next_page"></input>
    </form>
</response>

Each input item refers to a parameter, and specifies its name, whether it is a user-visible parameter, and whether it is required.

Client Expectations

We expect API clients to identify themselves uniquely by a User-agent header. This should identify, at minimum, the name of the application using the API, the version of the application, and a URI (web or email) at which we can get information about the application and/or contact the owner. Doing this will assist us in tracking down behavior problems with your application and/or resolve issues short of banning your application.

Place Marks

Each user can mark a place with one of four states: not_saved, to_visit, visited, or favorite. If a place is marked not_saved, it will not show up in the user's list of places. When a user adds or edits a place, or adds a note without a rating to a place, the place is marked to_visit. When a user adds a note with a rating to a place, the place is marked visited. The user may also edit this state manually through UI in the website.

The place mark state is set similarly in the API, in that various API calls that perform the above actions will modify the place mark state accordingly. API calls to modify the place mark state explicitly may also be used.

Additionally, a user's tags for a place are stored in a place mark. This is so tags added when a user adds or edits a place or note are shared among that place and all of the user's notes for that place.

Methods

auth/login

Logs in the user and returns a new session token.

Input Parameters

Name	Data Type	Required/Optional	Description
username	string	required	The username of the user to log in.
password	string	required	The password of the user to log in.

Example Response

<response version="1.0">
<request path="/api/auth/login"></request>
<token>ce2becc8346fdaf20bebefd880f0de16c8416728</token>
<logged-in status="yes"></logged-in>
</response>

auth/logout

Logs out the given user. This method uses the GET request method.

Input Parameters

Name	Data Type	Required/Optional	Description
token	string	required	Your session token.

Example Response

This is a failure due to a lack of token:

<response version="1.0">
<request path="/api/auth/logout"></request>
<logged-in status="yes"></logged-in>
<error code="100">Your token is required for this action.</error>
</response>

And this is a response on successful logout:

<response version="1.0">
<request path="/api/auth/logout"></request>
<logged-in status="no"></logged-in>
</response>

contacts/add

Adds a given user to your contacts list.

Input Parameters

Name	Data Type	Required/Optional	Description
username	string	required	The username of a user to add to your contacts list.
token	string	required	Your session token.

Example Response

<response version="1.0">
<request path="/api/contacts/add"></request>
<method-status success="yes"></method-status>
</response>

people/[username]/network

Returns the social network activity for the given person.

Input Parameters

Name	Data Type	Required/Optional	Description
username	string	required	The username of a user.
since_timestamp	float or int	optional	A UTC UNIX timestamp (optionally with floating point component). This will restrict the results to those that have been modified by the user since this time.
detailed	string	optional	Whether or not to show detailed information about the places. 'yes' if True, 'no' or omit if False.

Example Response

Event types will be one of REVIEW_ADD, REVIEW_EDIT, PLACE_ADD, or PLACE_EDIT for each event. More event types will be added in the future.

<?xml version="1.0" encoding="utf-8"?>
<response version="1.0">
  <request path="/api/people/buzz/network"></request>
  <events>
    <event username="andrew" type="PLACE_EDIT">
      <date>2008-09-25 05:45:17.268338</date>
      <place id="603" name="Cafe Rakka"></place>
    </event>
    <event username="andrew" type="REVIEW_EDIT">
      <date>2008-09-24 01:51:38.974476</date>
      <review username="andrew" place="602">
        <rating></rating>
        <notes></notes>
        <to_visit>yes</to_visit>
        <date>2008-09-24 00:37:34.106893</date>
        <last_modified>2008-09-24 01:51:38.974476</last_modified>
      </review>
    </event>
    <event username="andrew" type="REVIEW_ADD">
      <date>2008-09-24 00:37:34.106893</date>
      <review username="andrew" place="602">
        <rating></rating>
        <notes></notes>
        <to_visit>yes</to_visit>
        <date>2008-09-24 00:37:34.106893</date>
        <last_modified>2008-09-24 01:51:38.974476</last_modified>
      </review>
    </event>
    <event username="andrew" type="PLACE_EDIT">
      <date>2008-09-24 00:37:34.096372</date>
      <place id="602" name="California Academy of Sciences">
      </place>
    </event>
    <event username="andrew" type="PLACE_ADD">
      <date>2008-09-24 00:37:34.074629</date>
      <place id="602" name="California Academy of Sciences">
      </place>
    </event>
    ...
  </events>
</response>

people/[username]/places/tags/[tags]

Shows all the place marks with the given tags, as well as all the related tags for the given tag set.

Input Parameters

Name	Data Type	Required/Optional	Description
username	string	required	The username of a user.
tags	string	optional	The tags to filter on. Separate tags with slashes, like "restaurant/Mexican/taqueria".
since_timestamp	float or int	optional	A UTC UNIX timestamp (optionally with floating point component). This will restrict the results to those that have been modified by the user since this time.
detailed	string	optional	Whether or not to show detailed information about the places. 'yes' if True, 'no' or omit if False.

Example Response

<?xml version="1.0" encoding="utf-8"?>
<response version="1.0">
  <request path="/api/people/andrew/places/tags/restaurant/hole in the wall">
  </request>
  <query>
    <tags>
      <tag name="restaurant"></tag>
      <tag name="hole in the wall"></tag>
    </tags>
  </query>
  <related-tags>
    <tag count="1" name="bar"></tag>
    <tag count="1" name="barbeque"></tag>
    <tag count="1" name="bbq"></tag>
    <tag count="1" name="meat"></tag>
    <tag count="1" name="sushi"></tag>
  </related-tags>
  <place_marks>
    <place_mark username="andrew" place="54">
      <date>2008-07-25 00:56:11.058593</date>
      <last_modified>2009-04-14 02:19:42.883541</last_modified>
      <mark_type>visited</mark_type>
      <tags>
        <tag name="bar"></tag>
        <tag name="barbeque"></tag>
        <tag name="bbq"></tag>
        <tag name="hole in the wall"></tag>
        <tag name="meat"></tag>
        <tag name="restaurant"></tag>
      </tags>
    </place_mark>
    <place_mark username="andrew" place="50">
      <date>2008-07-25 00:53:50.061515</date>
      <last_modified>2009-04-14 02:19:42.908140</last_modified>
      <mark_type>visited</mark_type>
      <tags>
        <tag name="hole in the wall"></tag>
        <tag name="restaurant"></tag>
        <tag name="sushi"></tag>
      </tags>
    </place_mark>
  </place_marks>
</response>

people/[username]/notes

Shows all of the user's notes.

Input Parameters

Name	Data Type	Required/Optional	Description
username	string	required	The username of a user.
since_timestamp	float or int	optional	A UTC UNIX timestamp (optionally with floating point component). This will restrict the results to those that have been modified by the user since this time.
detailed	string	optional	Whether or not to show detailed information about the places. 'yes' if True, 'no' or omit if False.

Example Response

<response version="1.0">
  <request path="/api/people/buzz/notes"></request>
  <query>
    <username>buzz</username>
  </query>
  <notes>
    <note username="buzz" place="118">
      <rating>4.0</rating>
      <notes>Delicious "New Mexican" food (that is, burritos smothered in green chile and cheese). Noted for their Margaritas (they have variations that cost upwards of $45 on the menu).</notes>
      <date>2008-09-10 04:45:29.720162</date>
      <last_modified>2008-09-10 04:45:29.720184</last_modified>
    </note>
    <note username="buzz" place="104">
      <rating>4.0</rating>
      <notes>Great outdoor coffee shop with cool decor, decent food, and free wifi. Good people watching South Congress.</notes>
      <date>2008-09-10 03:10:35.940232</date>
      <last_modified>2008-09-10 03:10:35.940250</last_modified>
    </note>
  </notes>
</response>

places/add

Adds a place to the site. You may also optionally add a note of the place at the same time.

Input Parameters

Name	Data Type	Required/Optional	Description
name	string	required	The name of the place.
address1	string	optional	The first line of the address.
address2	string	optional	The second line of the address.
city	string	optional	The name of the city this is in.
state	string	optional	The name of the state.
country	string	optional	The ISO alpha 2 country code of a country in the country list (see places/countries).
postal_code	string	optional	The postal code of the address.
phone	string	optional	A phone number for this place.
fax	string	optional	A fax number for this place.
url	string	optional	A URL for the web site of this place.
tags	string	optional	Some tags to tag this place with.
latitude	float	optional	The latitude of this place, as a float (required if longitude given).
longitude	float	optional	The longitude of this place, as a float (required if latitude given).
altitude	float	optional	The longitude of this place, as a float. Units are meters.
accuracy	float	optional	The accuracy of your latitude/longitude, as a float. Units are meters. An accuracy of 5.0 means it is within plus or minus 5 meters.
token	string	required	Your session token.
rating	float	optional	A number between 0.0 and 5.0, inclusive.
notes	string	optional	Any notes the user may have on this place. Plain text. Newlines will be converted to line breaks on the site.

Example Response

<response version="1.0">
<request path="/api/places/add"></request>
<method-status place-id="2" success="yes"></method-status>
</response>

places/countries

Lists the countries and territories that can be used in adding a place.

There are two special countries in the list, Unknown (2 letter code ??) and Extraterritorial (2 letter code !x). The first is used as the default if no country is entered. The second should be used if the place exists outside of any one country's borders.

Input Parameters

None.

Example Response

<response version="1.0">
  <request path="/api/places/countries"></request>
  <countries>
    <country iso_alpha_2="AF">Afghanistan</country>
    <country iso_alpha_2="AX">Aland Islands</country>
    <country iso_alpha_2="AL">Albania</country>
    <country iso_alpha_2="DZ">Algeria</country>
    ...
    <country iso_alpha_2="ZM">Zambia</country>
    <country iso_alpha_2="ZW">Zimbabwe</country>
  </countries>
</response>

places/[place id]

Returns detailed information about a specific place.

Input Parameters

Name	Data Type	Required/Optional	Description
place_id	string	required	The id of the place.
detailed	string	optional	Whether or not to show notes of this place, as well. 'yes' if True, 'no' or omit if False.

Example Response (detailed)

<?xml version="1.0" encoding="utf-8"?>
<response version="1.0">
  <request path="/api/places/435"></request>
  <place id="435" name="The Violet Hour">
    <location latitude="41.908877" longitude="-87.677445" altitude="10.0"></location>
    <address1>1520 N. Damen Ave</address1>
    <address2></address2>
    <city>Chicago</city>
    <state>IL</state>
    <country iso_alpha_2="US">United States</country>
    <postal_code>60622</postal_code>
    <phone>(773) 252-1500</phone>
    <fax></fax>
    <url>http://www.theviolethour.com/</url>
    <rating_count>1</rating_count>
    <rating_average>5.0</rating_average>
    <neighborhoods>
      <neighborhood>West Town</neighborhood>
    </neighborhoods>
    <tags>
      <tag name="bar"></tag>
      <tag name="cocktails"></tag>
    </tags>
    <notes>
      <note username="buzz" place="435">
        <rating>5.0</rating>
        <notes>Absolutely the coolest looking and feeling bar I've ever been to--the apotheosis of the "speakeasy." The drinks were great too (really enjoyed a Manhattan variation with pine liqueur and Laphroig.</notes>
        <date>2008-09-10 03:01:15.086946</date>
        <last_modified>2008-09-10 03:01:15.086967</last_modified>
      </note>
    </notes>
  </place>
</response>

places/[place id]/vote

Users may vote on the information on a particular place by submitting place votes. These votes determine what information is displayed on a particular place. So, say, a bunch of people update the address of a place, we will endeavor to show the corrected address. If a user has already voted on a place, their previous information will be returned, and they may update that.

Input Parameters

Name	Data Type	Required/Optional	Description
place_id	string	required	The id of the place.
name	string	required	The name of the place.
address1	string	optional	The first line of the address.
address2	string	optional	The second line of the address.
city	string	optional	The name of the city this is in.
state	string	optional	The name of the state.
country	string	optional	The ISO alpha 2 country code of a country in the country list (see places/countries).
postal_code	string	optional	The postal code of the address.
phone	string	optional	A phone number for this place.
fax	string	optional	A fax number for this place.
url	string	optional	A URL for the web site of this place.
tags	string	optional	Some tags to tag this place with.
latitude	float	optional	The latitude of this place, as a float (required if longitude given).
longitude	float	optional	The longitude of this place, as a float (required if latitude given).
token	string	required	Your session token.

Example Response

<response version="1.0">
<request path="/api/places/1/vote"></request>
<method-status success="yes"></method-status>
</response>

places/[place id]/mark

Edits a user's mark associated with a given place..

Input Parameters

Name	Data Type	Required/Optional	Description
place_id	string	required	The id of the place.
mark_type	string	required	What state the mark is in. One of: not_saved, to_visit, visited, or favorite.
tags	string	optional	Some tags to tag this place with.
token	string	required	Your session token.

Example Response

<response version="1.0">
<request path="/api/places/1/mark"></request>
<method-status success="yes"></method-status>
</response>

/places/tags/[tags]

Shows all the places with the given tags, as well as all the related tags for the given tag set.

Input Parameters

Name	Data Type	Required/Optional	Description
tags	string	optional	The tags to filter on. Separate tags with slashes, like "restaurant/Mexican/taqueria".

Example Response

<?xml version="1.0" encoding="utf-8"?>
<response version="1.0">
  <request path="/api/places/tags/restaurant/Mexican/taqueria">
  </request>
  <query>
    <tags>
      <tag name="restaurant"></tag>
      <tag name="Mexican"></tag>
      <tag name="taqueria"></tag>
    </tags>
  </query>
  <tags>
    <tag count="1" name="bar"></tag>
    <tag count="1" name="cafe"></tag>
    <tag count="2" name="food"></tag>
  </tags>
  <places>
    <place id="107" name="La Esquina"></place>
    <place id="106" name="Pinche Taqueria"></place>
  </places>
</response>

notes/note_place/[place id]

This method allows a user to add a note to a place.

If the user notes a place they've marked as to_visit or not_saved and sets a rating, the place will be marked visited. If they do not set a rating, and the place has no place mark from this user or is marked not_saved, the place will be marked to_visit.

Input Parameters

Name	Data Type	Required/Optional	Description
place_id	string	required	The id of the place.
rating	float	required	A number between 0.0 and 5.0, inclusive.
rating_cancel	string	required	Determines whether or not the rating will be used. If you don't want to use the value of rating, this parameter should be "true". If you do want to use the value of rating, this parameter should be "false".
notes	string	optional	Any notes the user may have on this place. Plain text. Newlines will be converted to line breaks on the site.
tags	string	optional	A string of tags to associate with the place. This is shared among all notes.
token	string	required	Your session token.

Example Response

<response version="1.0">
<request path="/api/notes/note_place/1"></request>
<method-status success="yes"></method-status>
</response>

notes/[note id]/edit

This method allows you to edit an existing note.

Input Parameters

Name	Data Type	Required/Optional	Description
note_id	string	required	The id of the note to edit.
rating	float	required	A number between 0.0 and 5.0, inclusive.
rating_cancel	string	required	Determines whether or not the rating will be used. If you don't want to use the value of rating, this parameter should be "true". If you do want to use the value of rating, this parameter should be "false".
notes	string	optional	Any notes the user may have on this place. Plain text. Newlines will be converted to line breaks on the site.
tags	string	optional	A string of tags to associate with the place. This is shared among all notes.
token	string	required	Your session token.

Example Response

<response version="1.0">
<request path="/api/notes/1/edit"></request>
<method-status success="yes"></method-status>
</response>

notes/[note id]/delete

This method allows you to delete an existing note. The action must be submitted via a POST request.

Input Parameters

Name	Data Type	Required/Optional	Description
note_id	string	required	The id of the note to edit.
token	string	required	Your session token.

Example Response

<response version="1.0">
<request path="/api/notes/1/delete"></request>
<method-status success="yes"></method-status>
</response>

search/people

This method uses the HTTP GET method exclusively.

Input Parameters

Name	Data Type	Required/Optional	Description
query	string	required	The query string. Typically a username, first and last name, or last name.
page	integer	optional	The page number of the result set. Defaults to 1.
count	integer	optional	The number of results to return per page. Maximum is 100.

Example Response

<response version="1.0">
<request path="/api/search/people"></request>
<query>
  <page>1</page>
  <query>Andrew</query>
</query>
<results totalResults="1">
  <result username="andrew" name="Andrew Wooster" userpic_small="" userpic_large="" following="yes" is_same_user="no"></result>
</results>
</response>

Above, the following and is_same_user attributes should only be returned if the query was initiated by a logged-in users. The userpic_small and userpic_large fields will be either empty (no userpic) or set to absolute URLs to small and large user pictures, respectively.

search/places

This method uses the HTTP GET method exclusively.

Returned distances are in meters.

Input Parameters

Name	Data Type	Required/Optional	Description
query	string	optional	The query string. Typically a keyword to be found near the location.
location	string	required	The location. Typically a city or other place name. If the location is non-unique, a disambiguation result may be returned. May be omitted if a latitude and longitude are given.
latitude	float	optional	A latitude. When longitude is also given, overrides location.
longitude	float	optional	A longitude.
radius	float	optional	The radius from the given location in which to search. Units default to miles.
units	string	optional	The units to compute radius. Values are: mile, km, meter, and block.
page	integer	optional	The page number of the result set. Defaults to 1.
count	integer	optional	The number of results to return per page. Maximum is 100.
network	string	optional	Filters results by whether they are in the authenticated user's network or not. The default value is 'all', which shows all results. The value 'following' shows items either saved or reviewed by the user or their contacts.

Example Response (disambiguation)

<response version="1.0">
<request path="/api/search/places"></request>
<query>
  <location>Stanford</location>
</query>
<locations message="Please select the place which matches the location you entered.">
  <location latitude="37.424106" name="Stanford" longitude="-122.1660756"></location>
  <location latitude="38.5760164" name="Leland Stanford Mansion State Historic Park" longitude="-121.4980108"></location>
  <location latitude="39.2926837" name="Stanford (historical)" longitude="-120.2676989"></location>
  <location latitude="33.9511261" name="Stanford Avenue Park" longitude="-118.2217386"></location>
  <location latitude="37.4216059" name="Stanford Hills Park" longitude="-122.1977431"></location>
  <location latitude="37.4921559" name="Stanford Lake" longitude="-118.7842923"></location>
  <location latitude="33.654743" name="Stanford Park" longitude="-117.8433891"></location>
  <location latitude="38.5821275" name="Stanford Playground" longitude="-121.4660656"></location>
  <location latitude="37.4343835" name="Stanford Stadium" longitude="-122.1613533"></location>
</locations>
</response>

Example Response (search)

<response version="1.0">
<request path="/api/search/places"></request>
<query>
  <count>50</count>
  <location>37.447913, -122.1618</location>
  <page>1</page>
  <query></query>
  <radius>10</radius>
  <units>miles</units>
</query>
<results totalResults="49">
  <result distance="0" id="12254" name="Bangkok Cuisine"></result>
  <result distance="90.5" id="12331" name="Zibibbo"></result>
  <result distance="145" id="12277" name="Fratelli Deli"></result>
  ...
  <result distance="2043.86" id="9483" name="Luxie-Q BBQ Restaurant"></result>
</results>
</response>