Happenstand API Alpha

V1 Reference Guide

About

This is a very preliminary draft of an API (application programming interface) that would allow external parties to retrieve lists of event, venue and person data from Happenstand, a website featuring Bay Area arts events. It is NOT finalized therefore request URIs, parameters, and response schemas are all subject to change at any time without notice. There may also be bugs that return incorrect data or data in incorrect formats or be inconsistent with the documentation provided below. While functional, this is currently intended to serve as a point of discussion for potential further development. Thanks, Lucas.

Request an API key

To receive an API key, send an email to this address with a brief explanation of what you'd like to use the API for: api....@happenstand.com

Errors
Events
Images
Locales
Places
People
- People by name
- Person detail
Search
- Keyword search

Errors

Below is a list of common error codes and messages

Error code	Error message
100	API key is not valid
101	API key is not active
200	Missing required parameter (parameter)
201	Item not valid or unavailable
202	Could not determine query location
404	Resource not found
500	Application error

Response

Show sample XML response | Show sample JSON response

Events

Recently added and updated events

Get a list of events that have been recently added or updated for a location or all locations

Request URI

http://api.happenstand.com/v1/events/recent

Parameters	Description	Required	Default
api_key	API key	Y	N/A
loc	A locale ID to get events for. If left empty, will return events for all locales.	N	(empty)
offset	Position in results to begin response set	N	0
length	The number of events to return from the offset position	N	20
format	Format of response data (xml, json)	N	xml

Example requests

Get last 10 events added for San Francisco as XML
http://api.happenstand.com/v1/events/recent?api_key=API_KEY&loc=1&length=10&format=xml
Get last 20 events added for all locations as JSON
http://api.happenstand.com/v1/events/recent?api_key=API_KEY&format=json

Response

Show sample XML response | Show sample JSON response

<?xml version="1.0" encoding="utf-8"?>
<response status="ok">
    <events>
        <event id="1330" is_ap_pick="0" is_pickpocket="0">
            <name><![CDATA[The Fountain of Giant Teardrops]]></name>
            <start>2009-01-23 00:00:00</start>
            <end>2009-03-01 00:00:00</end>
            <all_day>1</all_day>
            <excerpt><![CDATA[Opening reception: January 23, 7-10 PM.  For "The fountain of giant teardrops" Neil LeDoux will present new paintings and drawings that continue ...]]></excerpt>
            <people><![CDATA[Neil Ledoux]]></people>
            <places><![CDATA[Silverman Gallery]]></places>
            <url>http://www.happenstand.com/sanfrancisco/events/1330-the-fountain-of-giant-teardrops</url>
            <image id="1232520424" dir="http://www.happenstand.com/images/upload/0/1330/" ext="jpg">
                <caption><![CDATA[Neil Ledoux Pigna, 60 x 48 inches, Oil on Canvas, 2009]]></caption>
            </image>
		</event>
    </events>
</response>

Close sample response

Events starting by date

Show a list of events starting from a date with optional number of days and maximum length.

Request URI

http://api.happenstand.com/v1/events/start

Parameters	Description	Required	Default
api_key	API key	Y	N/A
loc	A locale ID to get events for. If left empty, will return events for all locales.	N	(empty)
date	Start of date range to get events for YYYY-MM-DD.	N	(today's date)
days	The number of days to return opening events for.	N	1
length	The maximum number of events return.	N	(empty)
ap_pick	Filter Art Practical picks - empty returns all events, "true" returns only AP picks, "false" returns only events that are not AP picks	N	(empty)
format	Format of response data (xml, json)	N	xml

Example requests

Get new events for San Francisco on October 9, 2009 as XML
http://api.happenstand.com/v1/events/start?api_key=API_KEY&loc=1&date=2009-10-09&format=xml
Get all starting events for from October 9, 2009 through October 15, 2009 as JSON
http://api.happenstand.com/v1/events/start?api_key=API_KEY&date=2009-10-09&days=7&format=json

Response

Show sample XML response | Show sample JSON response

Events ending by date

Show a list of events ending on a date with optional maximum length.

Request URI

http://api.happenstand.com/v1/events/end

Parameters	Description	Required	Default
api_key	API key	Y	N/A
loc	A locale ID to get events for. If left empty, will return events for all locales.	N	(empty)
date	End of date range to get events for YYYY-MM-DD.	N	(today's date)
days	The number of days to return closing events for.	N	1
length	The maximum number of events return.	N	(empty)
ap_pick	Filter Art Practical picks - empty returns all events, "true" returns only AP picks, "false" returns only events that are not AP picks	N	(empty)
format	Format of response data (xml, json)	N	xml

Example requests

Get events ending on San Francisco on October 09, 2009 as XML
http://api.happenstand.com/v1/events/end?api_key=API_KEY&loc=1&date=2009-10-09&format=xml
Get all events ending between October 09, 2009 and October 15, 2009 as JSON
http://api.happenstand.com/v1/events/end?api_key=API_KEY&date=2009-10-09&days=7&format=json

Response

Show sample XML response | Show sample JSON response

Events by proximity

Show a list of events by proximity to a given location. Results are sorted by distance. Distances are in miles.

Request URI

http://api.happenstand.com/v1/events/proximity

Parameters	Description	Required	Default
api_key	API key	Y	N/A
query	Location to measure distance from. Could be a latitude/longitude coordinate formatted as "-37.123456,121.132442" or a textual location search such as "1234 jones st, ca" or "94710". Queries should be URL encoded.	Y	N/A
distance	Distance to limit search by (in miles)	N	1
length	The maximum number of events to return	N	20
format	Format of response data (xml, json)	N	xml

Example requests

Get a list of the 10 nearest events to the zip code 94103 as XML
http://api.happenstand.com/v1/events/proximity?api_key=API_KEY&query=94103&length=10
Get a list of the 20 nearest events to the street address 1234 Jones St, SF CA as JSON
http://api.happenstand.com/v1/events/proximity?api_key=API_KEY&query=1234+jones+st,+sf+ca&format=json
Get a list of the events nearest the latitude of 37.7726402 and longitude of -122.4099154 as XML
http://api.happenstand.com/v1/events/proximity?api_key=API_KEY&query=37.7726402,-122.4099154

Response

Show sample XML response | Show sample JSON response

Event detail

Show the details for a given event

Request URI

http://api.happenstand.com/v1/events/detail

Parameters	Description	Required	Default
api_key	API key	Y	N/A
id	Unique ID of item to retrieve data for	Y	N/A
format	Format of response data (xml, json)	N	xml

Example request

Get the details and full description for event 729 as XML
http://api.happenstand.com/v1/events/detail?api_key=API_KEY&id=729&format=xml

Response

Show sample XML response | Show sample JSON response

<?xml version="1.0" encoding="utf-8"?>
<response status="ok">
    <event id="2513" is_ap_pick="1" is_pickpocket="0">
        <name><![CDATA[Chance and Construction]]></name>
        <loc>1</loc>
        <start>2009-09-22 00:00:00</start>
        <end>2009-11-29 00:00:00</end>
        <all_day>1</all_day>
        <description><![CDATA[Featuring the color etchings of Tomma Abts    Crown Point Press announces an exhibition of prints by a diverse group of artists whose subject matter focuses on process. London-based painter Tomma Abts, for example, allows a mark or a technique to direct a composition. New York artist Brad Brown and the avant-garde composer John Cage permit chance operations to play a significant role in creating their work.     Tomma Abts, the focus of this exhibition, makes small-scale, consistently-sized paintings and drawings. This past spring she completed five color etchings, her first project at Crown Point Press. Abtsâ€™s style resists categorization. In a recent interview she explains, â€œI am not interested in translating something onto the canvas. It is all about starting with nothing as a givenâ€”maybe choosing a color, making a shape and going from there. I want to make it all up myself from scratch. I am intensely involved with the process of constructing.â€� In one of her etchings, for example, Abts began constructing an image by laying down bits of torn paper onto the copper plates; these shapes in the final work seem to cast shadows beneath ruled soft ground lines.  Also included in this exhibition are prints by Robert Barry,Terry Fox, Laura Owens, Markus Raetz, Ed Ruscha, and Richard Tuttle.]]></description>
        <url>http://www.happenstand.com/sanfrancisco/events/2513-chance-and-construction</url>
        <special_events>
            <event id="503" is_ap_pick="1" is_pickpocket="0">
                <name><![CDATA[Artist reception]]></name>
                <start>2009-10-22 18:00:00</start>
                <end>2009-10-22 20:00:00</end>
                <all_day>0</all_day>
            </event>
        </special_events>
        <people>
            <person id="2304" is_featured="0">
                <name><![CDATA[Tomma Abts]]></name>
            </person>
        </people>
        <places>  
            <place id="196">
                <name><![CDATA[Crown Point Press]]></name>
            </place>
        </places>
        <images>
            <image id="1253838095" dir="http://www.happenstand.com/images/upload/0/2513/" ext="jpg">
                <caption><![CDATA[Tomma Abts, Untitled (12 bits), 2009]]></caption>
            </image>
            <image id="1253838156" dir="http://www.happenstand.com/images/upload/0/2513/" ext="jpg">
                <caption><![CDATA[Tomma Abts, Untitled(brushstroke), 2009]]></caption>
            </image>
        </images>
    </event>
</response>

Close sample response

{
    "status":"ok",
    "event":{
        "id":"2513",
        "name":"Chance and Construction",
        "start":"2009-09-22 00:00:00",
        "end":"2009-11-29 00:00:00",
        "all_day":"1",
        "description":"Featuring the color etchings of Tomma Abts\r\n\r\nCrown Point Press announces an exhibition of prints by a diverse group of artists whose subject matter focuses on process. London-based painter Tomma Abts, for example, allows a mark or a technique to direct a composition. New York artist Brad Brown and the avant-garde composer John Cage permit chance operations to play a significant role in creating their work. \r\n\r\nTomma Abts, the focus of this exhibition, makes small-scale, consistently-sized paintings and drawings. This past spring she completed five color etchings, her first project at Crown Point Press. Abts\u2019s style resists categorization. In a recent interview she explains, \u201cI am not interested in translating something onto the canvas. It is all about starting with nothing as a given\u2014maybe choosing a color, making a shape and going from there. I want to make it all up myself from scratch. I am intensely involved with the process of constructing.\u201d In one of her etchings, for example, Abts began constructing an image by laying down bits of torn paper onto the copper plates; these shapes in the final work seem to cast shadows beneath ruled soft ground lines.\r\nAlso included in this exhibition are prints by Robert Barry,Terry Fox, Laura Owens, Markus Raetz, Ed Ruscha, and Richard Tuttle.",
        "loc":"1",
        "is_pickpocket":"0",
        "is_ap_pick":"1",
        "people":[
            {
                "id":"2304",
                "name":"Tomma Abts",
                "is_featured":"0"
            }
        ],
        "places":[
            {
                "id":"196",
                "name":"Crown Point Press"
            }
        ],
        "special_events":[
            {
                "id":"503",
                "name":"Artist reception",
                "start":"2009-10-22 18:00:00",
                "end":"2009-10-22 20:00:00",
                "all_day":"0",
                "is_pickpocket":"0",
                "is_ap_pick":"1"
            }
        ],
        "url":"http:\/\/www.happenstand.com\/sanfrancisco\/events\/2513-chance-and-construction",
        "images":[
            {
                "dir":"http:\/\/www.happenstand.com\/images\/upload\/0\/2513\/",
                "id":"1253838095",
                "ext":"jpg",
                "caption":"Tomma Abts, Untitled (12 bits), 2009"
			},
			{
                "dir":"http:\/\/www.happenstand.com\/images\/upload\/0\/2513\/",
                "id":"1253838156",
                "ext":"jpg",
                "caption":"Tomma Abts, Untitled(brushstroke), 2009"
            }
        ]
    }
}

Close sample response

Current Art Practical picks

Get a list of events that are Art Practical picks that are still running or opening in the future.

Request URI

http://api.happenstand.com/v1/events/picks

Parameters	Description	Required	Default
api_key	API key	Y	N/A
offset	Position in results to begin response set	N	0
length	The number of events to return from the offset position	N	20
format	Format of response data (xml, json)	N	xml

Example requests

Get first 20 current AP picks as XML
http://api.happenstand.com/v1/events/picks?api_key=API_KEY&format=xml

Response

Show sample XML response | Show sample JSON response

Images

Image nodes return the image directory, the image id and the image extension. There are 5 standard resize dimensions.

Suffix	Image size
_t	Thumbnail - 75 x 75 pixels
_s	Small - 100 pixels on longest side
_m	Medium - 240 pixels on longest size
_l	Large - 500 pixels on longest size
(empty)	Original file

Using the image info and the size suffix you can construct image URLs as such:

[dir] + [id] + [suffix] + . + [ext]

eg.
http://www.happenstand.com/images/upload/0/2560/1254765450_m.jpg

Locales

For now there is only one locale used on the site, Bay Area and its ID is 1. In the future if there are more locations, there would be a service to return a list of locales with IDs.

Places

Places by name

Get a list of places with current events summary

Request URI

http://api.happenstand.com/v1/places/list

Parameters	Description	Required	Default
api_key	API key	Y	N/A
start	A letter of the alphabet to filter results by, or '0' for items starting with numbers. If left empty, returns all items.	N	(empty)
loc	A locale ID to get events for. If empty, returns events for all locales.	N	(empty)
offset	Position in results to begin response set	N	0
length	Number of items to return from offset position. If empty, returns all items for current 'start' filter.	N	(empty)
format	Format of response data (xml, json)	N	xml

Example requests

Get a list of San Francisco all venues that start with the letter J as XML
http://api.happenstand.com/v1/places/list?api_key=API_KEY&loc=1&start=j&format=xml
Get a set of 10 venues from all locations starting with M and offset by 10 as JSON
http://api.happenstand.com/v1/places/list?api_key=API_KEY&start=m&offset=10&length=10&format=json

Response

Show sample XML response | Show sample JSON response

Places by proximity

Show a list of places by proximity to a given location. Results are sorted by distance. Distances are in miles.

Request URI

http://api.happenstand.com/v1/places/proximity

Parameters	Description	Required	Default
api_key	API key	Y	N/A
query	Location to measure distance from. Could be a latitude/longitude coordinate formatted as "-37.123456,121.132442" or a textual location search such as "1234 jones st, ca" or "94710". Queries should be URL encoded.	Y	N/A
distance	Distance to limit search by (in miles)	N	1
offset	Position in results to begin response set	N	0
length	Number of items to return from offset position	N	20
format	Format of response data (xml, json)	N	xml

Example requests

Get a list of the 10 nearest places to the zip code 94103 as XML
http://api.happenstand.com/v1/places/proximity?api_key=API_KEY&query=94103&length=10
Get a list of the 20 nearest places to the street address 1234 Jones St, SF CA as JSON
http://api.happenstand.com/v1/placs/proximity?api_key=API_KEY&query=1234+jones+st,+sf+ca&format=json
Get a list of the places nearest the latitude of 37.7726402 and longitude of -122.4099154 as XML
http://api.happenstand.com/v1/places/proximity?api_key=API_KEY&query=37.7726402,-122.4099154

Response

Show sample XML response | Show sample JSON response

Place detail

Show the details for a given place

Request URI

http://api.happenstand.com/v1/places/detail

Parameters	Description	Required	Default
api_key	API key	Y	N/A
id	Unique ID of item to retrieve data for	Y	N/A
format	Format of response data (xml, json)	N	xml

Example request

Get the details and upcoming events summary for place 137
http://api.happenstand.com/v1/places/detail?id=137

Response

Show sample XML response | Show sample JSON response

People

People by name

Show a list of people by name

Request URI

http://api.happenstand.com/v1/people/list

Parameters	Description	Required	Default
api_key	API key	Y	N/A
start	A letter of the alphabet to filter results by, or '0' for items starting with numbers. If left empty, returns all items.	N	(empty)
offset	Position in results to begin response set	N	0
length	Number of items to return from offset position. If empty, returns all items for current 'start' filter.	N	(empty)
format	Format of response data (xml, json)	N	xml

Example requests

Get all people with a last name starting with B as JSON
http://api.happenstand.com/v1/people/list?api_key=API_KEY&start=b&format=json
Get a set of 10 people starting at the 300th position of all names as XML
http://api.happenstand.com/v1/people/list?api_key=API_KEY&offset=300&length=10&format=xml

Response

Show sample XML response | Show sample JSON response

Person detail

Show the details for a given person with past and future event summaries

Request URI

http://api.happenstand.com/v1/people/detail

Parameters	Description	Required	Default
api_key	API key	Y	N/A
id	Unique ID of item to retrieve data for	Y	N/A
format	Format of response data (xml, json)	N	xml

Example request

Get the details for person 387
http://api.happenstand.com/v1/people/detail?api_key=API_KEY&id=387&format=xml

Response

Show sample XML response | Show sample JSON response

Search

Keyword search

Show event, place and people matches for a search word or term. Results are ordered by a score measuring precision of match to query (0-1).

Request URI

http://api.happenstand.com/v1/search

Parameters	Description	Required	Default
api_key	API key	Y	N/A
query	The keyword(s) to find matches for. Queries should be URL encoded.	Y	N/A
format	Format of response data (xml, json)	N	xml

Example requests

Search for matches to the keyword "ruins" as XML
http://api.happenstand.com/v1/search?api_key=API_KEY&query=ruins&format=xml
Search for matches to the keyword "Scholz" as JSON
http://api.happenstand.com/v1/search?api_key=API_KEY&query=Scholz&format=json

Response

Show sample XML response | Show sample JSON response

Happenstand API Alpha

V1 Reference Guide

About

Request an API key

Contents

Errors

Response

Events

Recently added and updated events

Request URI

Example requests

Response

Events starting by date

Request URI

Example requests

Response

Events ending by date

Request URI

Example requests

Response

Events by proximity

Request URI

Example requests

Response

Event detail

Request URI

Example request

Response

Current Art Practical picks

Request URI

Example requests

Response

Images

Locales

Places

Places by name

Request URI

Example requests

Response

Places by proximity

Request URI

Example requests

Response

Place detail

Request URI

Example request

Response

People

People by name

Request URI

Example requests

Response

Person detail

Request URI

Example request

Response

Search

Keyword search

Request URI

Example requests

Response