ArtBeat API: New York

Mash up New York Art Beat and base your Web application on the best Art and Design information for your city of choice.

The ArtBeat API is available free of charge for non-commercial applications which do not cause unreasonable traffic.

Your applications based on this API should follow these simple rules

  • • The apps should mention that they are “Powered by NY Art Beat”, with a link to www.nyartbeat.com
  • • (if applicable) any link for “more information” on events or venues should point to www.nyartbeat.com
  • • whenever possible, data retrieved from the API should be cached by your application for at least one hour and no more than one day

Please leave a message on our Art Beat API Google Group if:

  • • you have issues with the API
  • • you want to share your progress
  • • it's time to announce your new application built using the API

Please contact us if:

  • • you are developing, or have developed, a commercial application based on the API
  • • your application is likely to cause heavy traffic on the API

Note: The ArtBeat API also includes data for Tokyo Art Beat. Check the Tokyo Art Beat API page for more details.

ArtBeat API XML Output

The ArtBeat API uses a consistent XML format for all the lists and methods returning a list of events.

The XML output formats lists <Events> (as root element) with children as described below:

ElementChildrenValue, Notes
EventName, Venue, Description, Image, Karma, Price, DateStart, DateEnd, PermanentEvent, Distance, Datum, Latitude, LongitudeHolds all the info for a single event
VenueName, TypeHolds all the info for an event's venue
NameName of event/venue, in the chosen/default language
TypeType of venue (Museum, etc)
MediaNote: an Event can have several Media
Descriptionescaped as CDATA
Imageembed the poster / image of the event. May have a width attribute, in pixels. Note: an Event can have several Images (several sizes)
KarmaPopularity of the events decided by the MyTAB users
PriceEntry price for the event. Has a "free" attribute equal to 1 if the event is free, 0 otherwise.
DateStartYYYY-MM-DD
DateEndYYYY-MM-DD
PermanentEvent1 = permanent event; 0 = non-permanent event
DistanceDistance from the searched location. Not returned in non-search lists.in meters
DatumDatum of latitude/longitude coordinates. world for the worldwide standard WGS84 geolocation datum, or tokyo for Tokyo Datum used by a number of services in Japan.
Latitudedecimal coordinates
Longitudedecimal coordinates

Changelog

As of August 2008, the ArtBeat API uses the version 0.1 (beta) of its XML result format. This is the first version of the format.

Sample Output

<?xml version="1.0"?>
<Events>
<Event xml:lang="en" id="2008/249F" href="http://www.nyartbeat.com/event/2008/249F">
  <Name>&quot;Take Me Out to the Ballgame&quot; Exhibition</Name>
  <Venue href="http://www.nyartbeat.com/venue/3C79FC1F">
    <Name>The New York Public Library for the Performing Arts</Name>
    <Type>Other</Type>
  </Venue>
  <Description><![CDATA[An exhibition for the whole family! To celebrate the 100th anniversary of baseball theme songs, The New York Public Library for the Performing Arts presents ...]]></Description>
  <Image src="http://www.nyartbeat.com/media/event/2008/32B2-30" width="30" />
  <Image src="http://www.nyartbeat.com/media/event/2008/32B2-80" width="80" />
  <Image src="http://www.nyartbeat.com/media/event/2008/32B2-170" width="170" />
  <Karma>0</Karma>
  <Price free="0">Adults 4$, Students 2$</Price>
  <DateStart>2008-07-08</DateStart>
  <DateEnd>2008-10-28</DateEnd>
  <DaysBeforeEnd>88</DaysBeforeEnd>
  <PermanentEvent>0</PermanentEvent>
  <Distance>177.0156764</Distance>
  <Datum>wgs84</Datum>
  <Latitude>40.772258</Latitude>
  <Longitude>-73.983194</Longitude>
</Event>
</Events>

API Method: event_searchNear

The event_searchNear method is available at the following URL:

http://www.nyartbeat.com/list/event_searchNear

Requests are made with the GET HTTP method, with REST-style parameters sent in the query string.

Parameters

Location Search Parameters
Latitude (required) coordinates in decimal (xxx.xxxxxx) format
up to 6 digit precision. Anything beyond that precision is ignored
Longitude (required) coordinates in decimal (xxx.xxxxxx) format
up to 6 digit precision. Anything beyond that precision is ignored
Data Selection Parameters
Schedule
  1. "current" = currently open events (default)
  2. "upcoming" = events opening today or later
SearchRange
  1. 500m (default),
  2. 1000m,
  3. 1500m,
  4. 3000m
Description
  1. "" = only events with a description (default)
  2. "all" = all events even those without a description
Free
  1. "1" = free events only
  2. "0" = all events regarless of price (default)
Result Parameters
Language
  1. "ja" = Japanese (default)
  2. "en" = English
MaxResults "5", "10", "20" or "50"
SortOrder
  1. "distance" = nearest events (default)
  2. "closingsoon" = events that close the sooner first
  3. "mostpopular" = events with the most bookmarks first

Note: All parameters and values are case-INsensitive to be user-friendly.

Samples Queries

  • http://www.nyartbeat.com/list/event_searchNear?latitude=40.719130&longitude=-73.980000
    nearest events to the location specified
  • http://www.nyartbeat.com/list/event_searchNear?latitude=40.719130&longitude=-73.980000&MaxResults=5&SortOrder=distance&free=1
    (Nearest free events, max 5 results)
  • http://www.nyartbeat.com/list/event_searchNear?latitude=40.719130&longitude=-73.980000&Schedule=upcoming&SortOrder=mostpopular
    (Most popular upcoming events)
  • http://www.nyartbeat.com/list/event_searchNear?latitude=40.719130&longitude=-73.980000&SortOrder=mostpopular&Free=1
    (Most popular events, free only)
  • http://www.nyartbeat.com/list/event_searchNear?latitude=40.719130&longitude=-73.980000&SortOrder=closingsoon
    (Events closing soon)

AS3 Wrapper

The AS3 Artbeat API is a handy Actionscript 3.0 wrapper that any flash developer can use to access our Art Beat APIs.
More details and download from Reuben Stanton's AS3 Artbeat API site.

Sites & Applications

A few apps and websites have already surfaced that make use of the Artbeat API:

  • New York art info in your inbox!
    Hot exhibitions, openings, reviews, & more for free!

    All content on this site is © their respective owner(s).
    New York Art Beat (2008) - About - Contact - Privacy - Terms of Use