Localist API Documentation

Overview

The Localist API is a simple HTTP-based interface. Standard HTTP calls will return XML your application can use.

Usage

All the methods described live under http://www.localist.com/api/. A simple HTTP GET request can be made to retrieve results. Methods that change data require a HTTP POST.

Response Format

On success, the API returns XML as described with each method. The following HTTP status codes are returned:

Code	Description
200	Response succeeded
400	Error handling request
401	Authentication error
403	Forbidden
404	Not found
500	Internal error

Responses with codes 400 and 401 will have a hash in the body containing the error message. For example:

<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <request>/api/cities</request>
  <error>Invalid application key</error>
</hash>

Application Keys

A valid application key must be provided with each request in the api_key parameter. You can find your application key on your account settings page.

Calls with a missing or invalid application key will fail with a 401 response.

At this time API calls are not rate limited.

Method Summary

Request parameters and response formats are described on the linked pages.

Note: All example requests need to have your application key inserted in place of the APP_KEY placeholder.

Locality

Call	Description
/cities	List available cities
/city/city_id	Get details about a city
/city/city_id/neighborhoods	List neighborhoods in a city
/city/city_id/neighborhood/neighborhood_id	Get details about a neighborhood

Venues

Call	Description
/venue/venue_id	Get details about a venue
/venue/venue_id/reviews	Get reviews of a venue

Events

Call	Description
/events	Get a list of events in a city or at a venue
/event/types	Get the list of valid event types
/event/event_id	Get details about an event
/event/event_id/reviews	Get reviews of an event
/city/city_id/top_events	Get listing of highest-ranked events (also available for neighborhoods)

Locality Method Overview

These methods retrieve information about cities and neighborhoods.

To retrieve event listings for a city or neighborhood, see the /events method.

City XML Format

A city is represented with the following XML:

<city>
  <id>1</id>
  <name>Baltimore</name>
  <description>Known for its gritty locales...</description>
  <sister_city_id>2</sister_city_id>
  <neighborhoods type="array">
    <neighborhood>
      <id>2</id>
      <city_id>1</city_id>
      <name>Canton</name>
      <description>The neighborhood, located in...</description>
    </neighborhood>
    <!-- repeated ... -->
  </neighborhoods>
  <localist_url>http://www.localist.com/baltimore</localist_url>
</city>

Element	Description
`id`	The ID of the city (used as `city_id` in other methods)
`name`	The name of the city
`description`	Description of the city
`sister_city_id`	ID of a related city (for instance, Baltimore points to DC)
`neighborhoods`	Array of neighborhoods in this city
`localist_url`	URL of the city’s page on Localist

Neighborhood XML Format

A neighborhood is represented with the following XML:

<?xml version="1.0" encoding="UTF-8"?>
<neighborhood>
  <id>1</id>
  <city_id>1</city_id>
  <name>Fells Point</name>
  <description>Beware the wharf rat...</description>
  <localist_url>http://www.localist.com/baltimore/fellspoint</localist_url>
</neighborhood>

Element	Description
`id`	The ID of the neighborhood (used as `neighborhood_id` in other methods)
`city_id`	The ID of the city this neighborhood is in
`name`	The name of the neighborhood
`description`	Description of the neighborhood
`localist_url`	URL of the neighborhood’s page on Localist

Methods

City List

Method: /cities

Returns a list of available cities.

A list of <city> elements will be returned in the <cities> element.

Parameters	Description
`api_key`	Required, the application key

Example request: http://www.localist.com/api/cities?api_key=APP_KEY

Response: (portions truncated)

<?xml version="1.0" encoding="UTF-8"?>
<cities type="array">
  <city>
    <id>1</id>
    <name>Baltimore</name>
    <description>Known for its gritty locales...</description>
    <sister_city_id>2</sister_city_id>
    <neighborhoods type="array">
      <neighborhood>
        <id>2</id>
        <city_id>1</city_id>
        <name>Canton</name>
        <description>The neighborhood, located in...</description>
      </neighborhood>
      <!-- truncated ... -->
    </neighborhoods>
    <localist_url>http://www.localist.com/baltimore</localist_url>
  </city>
  <!-- truncated ... -->
</cities>

Get City Details

Method: /city/city_id

Returns details about the city specified by city_id.

Parameters	Description
`api_key`	Required, the application key

Example request: http://www.localist.com/api/city/1?api_key=APP_KEY

Response: (portions truncated)

<city>
  <id>1</id>
  <name>Baltimore</name>
  <description>Known for its gritty locales...</description>
  <sister_city_id>2</sister_city_id>
  <neighborhoods type="array">
    <neighborhood>
      <id>2</id>
      <city_id>1</city_id>
      <name>Canton</name>
      <description>The neighborhood, located in...</description>
    </neighborhood>
    <!-- repeated ... -->
  </neighborhoods>
  <localist_url>http://www.localist.com/baltimore</localist_url>
</city>

Get City Neighborhoods

Method: /city/city_id/neighborhood/neighborhood_id

Returns the neighborhoods of the city specified by city_id.

A list of <neighborhood> elements will be returned in the <neighborhoods> element.

Parameters	Description
`api_key`	Required, the application key

Example request: http://www.localist.com/api/city/1/neighborhoods?api_key=APP_KEY

Response: (portions truncated)

<?xml version="1.0" encoding="UTF-8"?>
<neighborhoods type="array">
  <neighborhood>
    <id>2</id>
    <city_id>1</city_id>
    <name>Canton</name>
    <description>The neighborhood...</description>
    <localist_url>http://www.localist.com/baltimore/canton</localist_url>
  </neighborhood>
  <!-- truncated ... -->
</neighborhoods>

Get Neighborhood Details

Method: /city/city_id/neighborhood/neighborhood_id

Returns details of the neighborhood specified by city_id and neighborhood_id.

Parameters	Description
`api_key`	Required, the application key

Example request: http://www.localist.com/api/city/1/neighborhood/1?api_key=APP_KEY

Response: (portions truncated)

<?xml version="1.0" encoding="UTF-8"?>
<neighborhood>
  <id>1</id>
  <city_id>1</city_id>
  <name>Fells Point</name>
  <description>Beware the wharf rat...</description>
  <localist_url>http://www.localist.com/baltimore/fellspoint</localist_url>
</neighborhood>

Venue Method Overview

These methods retrieve information about venues.

To retrieve event listings for a venue, see the /events method.

Venue XML Format

A venue is represented with the following XML:

<?xml version="1.0" encoding="UTF-8"?>
<venue>
  <id>12</id>
  <name>Fletcher's Bar &amp; Grill</name>
  <city_id>1</city_id>
  <neighborhood_id>1</neighborhood_id>
  <description>Mid-sized live...</description>
  <type>Bar</type>
  <editors_pick>false</editors_pick>
  <directions>Take 95 South to...</directions>
  <dress_code>Casual</dress_code>
  <editorial_description></editorial_description>
  <has_food_service>true</has_food_service>
  <has_full_bar>true</has_full_bar>
  <audience>Average Joes</audience>
  <price_range>Midrange</price_range>
  <parking>Street...</parking>
  <phone>410-558-1889</phone>
  <address>701 S Bond St, Baltimore, MD 21231, USA</address>
  <url>http://www.fletchersbar.com/</url>
  <ranking>100</ranking>
  <last_modified>2009-05-14T22:28:55Z</last_modified>
  <geo>
    <latitude>39.283447</latitude>
    <longitude>-76.59519</longitude>
    <street_1>701 S Bond St</street_1>
    <locality>Baltimore</locality>
    <region>MD</region>
    <country>US</country>
    <zip>21231</zip>
  </geo>
  <localist_url>http://www.localist.com/...</localist_url>
  <photo_url>http://images.localist.com/...</photo_url>
</venue>

Element	Description
`id`	The ID of the venue (used as `venue_id` in other methods)
`name`	The name of the venue
`city_id`	The city where the venue is located
`neighborhood_id`	The neighborhood where the venue is located
`description`	Description of the venue
`type`	The type of venue
`editors_pick`	`true` if this is an editor’s pick, `false` otherwise
`directions`	Directions
`dress_code`	The dress code of the venue
`editorial_description`	Description of venue provided by Localist editors
`has_after_hours`	`true` if has after hours. (`false` may be absent)
`has_food_service`	`true` if the venue has food service
`has_full_bar`	`true` if the venue has a full bar
`has_outside_area`	`true` if the venue has an outdoor area
`audience`	The type of audience at the venue
`price_range`	Price range
`parking`	Details about parking
`phone`	Phone number of the venue
`address`	Street address of the venue
`url`	URL to the venue’s site (not the Localist page)
`ranking`	Ranking of the venue’s popularity, 0-100
`last_modified`	Last modification date/time
`geo`	Geographical information, see below
`localist_url`	URL of the venue’s page on Localist
`photo_url`	URL of the venue’s image

Geo XML info

Contains structured geographic information. Any or all of these elements may be missing if the address was not recognized.

<geo>
  <latitude>39.283447</latitude>
  <longitude>-76.59519</longitude>
  <street_1>701 S Bond St</street_1>
  <locality>Baltimore</locality>
  <region>MD</region>
  <country>US</country>
  <zip>21231</zip>
</geo>

Element	Description
`latitude`	Latitude of the address
`longitude`	Longitude of the address
`street_1`	Street portion of address
`street_2`
`locality`	City, etc. of address
`region`	State portion of address
`country`	Country where address is
`zip`	Postal code of address

Review XML info

<?xml version="1.0" encoding="UTF-8"?>
<review>
  <id>313</id>
  <rating>1</rating>
  <comment>Upstairs and downstairs...</comment>
  <review_of>business</review_of>
  <business_id>12</business_id>
  <created_at>2009-04-16T01:52:06Z</created_at>
  <updated_at>2009-04-16T01:52:06Z</updated_at>
  <reviewer_id>3174</reviewer_id>
  <reviewer_username>CHA_Karaoke</reviewer_username>
  <reviewer>Adam</reviewer>
</review>

Element	Description
`id`	ID of the review
`rating`	Rating associated with the review (1 = thumbs up, 0 = neutral, -1 = thumbs down)
`comment`	Comment associated with the review
`review_of`	Either `event` or `business`, depending on what the review is attached to
`business_id`	(Venue reviews only) ID of the venue that was reviewed
`event_id`	(Event reviews only) ID of the event that was reviewed
`event_date`	(Event reviews only) Date of the event that was reviewed
`created_at`	When the review was posted
`reviewer_id`	ID of user who posted the review
`reviewer_username`	Username (for URLs) of user who posted the review
`reviewer`	Display name of user who posted the review

Meta XML info

Contains information about result paging, etc.

<meta>
  <page>1</page>
  <pp>10</pp>
  <num_pages>1</num_pages>
</meta>

Element	Description
`page`	Page number of returned results
`pp`	Number of results returned per page
`num_pages`	Total number of pages for all data

Methods

Get Venue Details

Method: /venue/venue_id

Returns details about the venue specified by venue_id.

Parameters	Description
`api_key`	Required, the application key

Example request: http://www.localist.com/api/venue/12?api_key=APP_KEY

Response: (portions truncated)

<?xml version="1.0" encoding="UTF-8"?>
<venue>
  <id>12</id>
  <name>Fletcher's Bar &amp; Grill</name>
  <city_id>1</city_id>
  <neighborhood_id>1</neighborhood_id>
  <description>Mid-sized live...</description>
  <type>Bar</type>
  <editors_pick>false</editors_pick>
  <directions>Take 95 South to...</directions>
  <dress_code>Casual</dress_code>
  <editorial_description></editorial_description>
  <has_food_service>true</has_food_service>
  <has_full_bar>true</has_full_bar>
  <audience>Average Joes</audience>
  <price_range>Midrange</price_range>
  <parking>Street...</parking>
  <phone>410-558-1889</phone>
  <address>701 S Bond St, Baltimore, MD 21231, USA</address>
  <url>http://www.fletchersbar.com/</url>
  <ranking>100</ranking>
  <last_modified>2009-05-14T22:28:55Z</last_modified>
  <geo>
    <latitude>39.283447</latitude>
    <longitude>-76.59519</longitude>
    <street_1>701 S Bond St</street_1>
    <locality>Baltimore</locality>
    <region>MD</region>
    <country>US</country>
    <zip>21231</zip>
  </geo>
  <localist_url>http://www.localist.com/...</localist_url>
  <photo_url>http://images.localist.com/...</photo_url>
</venue>

Get Venue Reviews

Method: /venue/event_id/reviews/

Returns the reviews of the venue specified by venue_id.

A list of <review> elements will be returned in the <reviews> element. A <meta> element will also be returned with details about total review count and paging.

Parameters	Description
`api_key`	Required, the application key
`pp`	Number of reviews to return (1-50, default 10)
`page`	Page number of results (default 1, counts from 1)

Example request: http://www.localist.com/api/venue/12/reviews?pp=10&page=1&api_key=APP_KEY

Response: (portions truncated)

<?xml version="1.0" encoding="UTF-8"?>
<reviews>
  <review>
    <id>313</id>
    <rating>1</rating>
    <comment>Upstairs and downstairs...</comment>
    <review_of>business</review_of>
    <business_id>12</business_id>
    <created_at>2009-04-16T01:52:06Z</created_at>
    <updated_at>2009-04-16T01:52:06Z</updated_at>
    <reviewer_id>3174</reviewer_id>
    <reviewer_username>CHA_Karaoke</reviewer_username>
    <reviewer>Adam</reviewer>
  </review>
  <meta>
    <page>1</page>
    <pp>10</pp>
    <num_pages>1</num_pages>
  </meta>
</reviews>

Event Method Overview

These methods retrieve information about events.

Event XML Format

A venue is represented with the following XML:

<?xml version="1.0" encoding="UTF-8"?>
<event>
  <id>9044</id>
  <title>WordCamp Mid-Atlantic</title>
  <description>WordPress is now...</description>
  <type>Technology</type>
  <keywords type="array">
    <keyword type="hashtag">#wordcampmidatl</keyword>
  </keywords>
  <url>http://wordcampmidatlantic.eventbrite.com/</url>
  <organizer>Localist</organizer>
  <last_modified>2009-05-11T20:14:47Z</last_modified>
  <geo>
    <location>University of Baltimore Thumel Business Center</location>
    <latitude>39.305246</latitude>
    <longitude>-76.616582</longitude>
    <street_1>11 W Mt Royal Ave</street_1>
    <locality>Baltimore</locality>
    <region>MD</region>
    <country>US</country>
    <zip>21201</zip>
  </geo>
  <city_id>1</city_id>
  <neighborhood_id>5</neighborhood_id>
  <event_instances type="array">
    <event_instance>
      <id>25256</id>
      <event_id>9044</event_id>
      <start>2009-05-16T08:00:00Z</start>
      <end>2009-05-16T17:00:00Z</end>
      <class>Public</class>
      <ticket_info>http://wordcampmidatlantic.eventbrite.com/</ticket_info>
      <ticket_price>$25 for admission, up to $500</ticket_price>
      <age_requirement>0</age_requirement>
      <ranking>19</ranking>
    </event_instance>
  </event_instances>
  <localist_url>http://www.localist.com/baltimore/event/word</localist_url>
  <photo_url>http://images.localist.com/...</photo_url>
</event>

Element	Description
`id`	The ID of the event (used as `event_id` in other methods)
`title`	The name of the event
`description`	Description of the event
`type`	The type of event
`keywords`	List of keywords/tags associated with the event (the `type` of individual `keyword`s will either be `tag` or `hashtag`)
`url`	URL to the venue’s site (not the Localist page)
`organizer`	Always “Localist”
`last_modified`	Last modification date/time
`geo`	Geographical information, see below
`city_id`	The city where the venue is located
`neighborhood_id`	The neighborhood where the venue is located
`event_instances`	List of instances of this event, see below
`localist_url`	URL of the event’s page on Localist
`photo_url`	URL of the event’s image

Event Instance XML info

Represents information about one specific instance of an event.

<event_instance>
  <id>25256</id>
  <event_id>9044</event_id>
  <start>2009-05-16T08:00:00Z</start>
  <end>2009-05-16T17:00:00Z</end>
  <class>Public</class>
  <ticket_info>http://wordcampmidatlantic.eventbrite.com/</ticket_info>
  <ticket_price>$25 for admission, up to $500 for sponsorships</ticket_price>
  <age_requirement>0</age_requirement>
  <ranking>19</ranking>
</event_instance>

Element	Description
`id`	The ID of the event instance
`event_id`	The ID of the event this instance is a part of
`start`	The date/time this instance starts
`end`	The date/time this instance ends (optional)
`class`	The visibility of this event, “Public” or “Private”
`ticket_info`	URL for information about tickets
`ticket_price`	Pricing information for the event
`age_requirement`	Age requirement of the instance (either `0`, `18` for 18+, or `21` for 21+)
`ranking`	Ranking of the event instance’s popularity, 0-100

Geo XML info

Contains structured geographic information. Any or all of these elements may be missing if the address was not recognized.

<geo>
  <location>University of Baltimore Thumel Business Center</location>
  <latitude>39.305246</latitude>
  <longitude>-76.616582</longitude>
  <street_1>11 W Mt Royal Ave</street_1>
  <locality>Baltimore</locality>
  <region>MD</region>
  <country>US</country>
  <zip>21201</zip>
</geo>

Element	Description
`location`	Name of venue
`location_id`	(optional) Venue ID of venue hosting this event
`latitude`	Latitude of the address
`longitude`	Longitude of the address
`street_1`	Street portion of address
`street_2`
`locality`	City, etc. of address
`region`	State portion of address
`country`	Country where address is
`zip`	Postal code of address

Review XML info

<?xml version="1.0" encoding="UTF-8"?>
<review>
  <id>313</id>
  <rating>1</rating>
  <comment>Upstairs and downstairs...</comment>
  <review_of>business</review_of>
  <business_id>12</business_id>
  <created_at>2009-04-16T01:52:06Z</created_at>
  <updated_at>2009-04-16T01:52:06Z</updated_at>
  <reviewer_id>3174</reviewer_id>
  <reviewer_username>CHA_Karaoke</reviewer_username>
  <reviewer>Adam</reviewer>
</review>

Element	Description
`id`	ID of the review
`rating`	Rating associated with the review (1 = thumbs up, 0 = neutral, -1 = thumbs down)
`comment`	Comment associated with the review
`review_of`	Either `event` or `business`, depending on what the review is attached to
`business_id`	(Venue reviews only) ID of the venue that was reviewed
`event_id`	(Event reviews only) ID of the event that was reviewed
`event_date`	(Event reviews only) Date of the event that was reviewed
`created_at`	When the review was posted
`reviewer_id`	ID of user who posted the review
`reviewer_username`	Username (for URLs) of user who posted the review
`reviewer`	Display name of user who posted the review

Meta XML info

Contains information about result paging, etc.

<meta>
  <page>1</page>
  <pp>10</pp>
  <num_pages>1</num_pages>
</meta>

Element	Description
`page`	Page number of returned results
`pp`	Number of results returned per page
`num_pages`	Total number of pages for all data

Methods

List Events

Method: /events
City: /city/city_id/events
Neighborhood: /city/city_id/neighborhood/neighborhood_id/events
Venue: /venue/venue_id/events

Returns a list of events happening in the specified city, neighborhood or venue.

The /events method can be used to retrieve event listings for all sources, however the alternative forms are provided for convenience.

The events will be returned in the <events> element. A <meta> element will be returned with result paging information.

Parameters	Description
`api_key`	Required, the application key
`city_id`	The city to return events for
`neighborhood_id`	The neighborhood to return events for
`venue_id`	The venue to return events for
`start`	The date (YYYY-MM-DD) starting the listing range (optional, defaults to today)
`end`	The date (YYYY-MM-DD) ending the listing range (optional, defaults to today)
`pp`	Number of events to return (1-50, defaults to 10)
`page`	Page number of results to return (defaults to 1, counts from 1)
`type` or `type[]`	Limit events to the specified type(s).
`sort`	Sort returned results by `date` ascending or `ranking` descending (default: `date`).

At least one of city_id, neighborhood_id or venue_id is required. The alternate forms automatically set these parameters.

The range specified by start to end must be no more than 31 days. If the a larger range is specified, end will be adjusted to 31 days after start.

Specified event types must be a value returned from the /event/types method. To specify multiple values, the parameter type[] may be repeated.

Example city request: http://www.localist.com/api/city/1/events?api_key=APP_KEY&start=2009-05-18&end=2009-05-24

Example neighborhood request: http://www.localist.com/api/city/1/neighborhood/1/events?api_key=APP_KEY&start=2009-05-18&end=2009-05-24

Example venue request: http://www.localist.com/api/venue/42/events?api_key=APP_KEY&start=2009-05-18&end=2009-05-24

Response: (portions truncated)

<events type="array">
  <event>
    <id>11252</id>
    <title>The Shins</title>
    <description>For The Shins...</description>
    <type>Concert/DJ</type>
    <genre>Indie</genre>
    <keywords type="array">
      <keyword type="hashtag">the_shins</keyword>
    </keywords>
    <url>http://www.theshins.com</url>
    <organizer>Localist</organizer>
    <last_modified>2009-04-16T19:11:41Z</last_modified>
    <geo>
      <location>Rams Head Live!</location>
      <location_id>42</location_id>
      <latitude>39.288289</latitude>
      <longitude>-76.606923</longitude>
      <street_1>20 Market Pl</street_1>
      <locality>Baltimore</locality>
      <region>MD</region>
      <country>US</country>
      <zip>21202</zip>
    </geo>
    <city_id>1</city_id>
    <neighborhood_id>4</neighborhood_id>
    <event_instances type="array">
      <event_instance>
        <id>32472</id>
        <event_id>11252</event_id>
        <start>2009-05-15T19:30:00Z</start>
        <class>Public</class>
        <ticket_info>http://tickets.ramsheadlive.com/...</ticket_info>
        <ticket_price>$35</ticket_price>
        <age_requirement>0</age_requirement>
        <ranking>9</ranking>
      </event_instance>
    </event_instances>
    <localist_url>http://www.localist.com/...</localist_url>
    <photo_url>http://images.localist.com/...</photo_url>
  </event>
  <!-- repeated ... -->
  <meta>
    <page>1</page>
    <pp>10</pp>
    <num_pages>1</num_pages>
  </meta>
</events>

List Event Types

Method: /event/types

Returns the list of event types. The types can be used in the type parameter to /event/list

Parameters	Description
`api_key`	Required, the application key

Example request: http://www.localist.com/api/event/types?api_key=APP_KEY

Response:

<?xml version="1.0" encoding="UTF-8"?>
<event_types type="array">
  <event_type>Concert/DJ</event_type>
  <event_type>Dance Event</event_type>
  <event_type>Theme Night</event_type>
  <event_type>Bar/Restaurant Special</event_type>
  <event_type>Performing Arts/Theater</event_type>
  <event_type>Visual Arts</event_type>
  <event_type>Festival</event_type>
  <event_type>Sport &amp; Action</event_type>
  <event_type>Outdoor &amp; Leisure</event_type>
  <event_type>Technology</event_type>
  <event_type>Holiday</event_type>
  <event_type>Other</event_type>
</event_types>

Get Event Details

Method: /event/venue_id

Returns details about the event specified by event_id.

Parameters	Description
`api_key`	Required, the application key

Example request: http://www.localist.com/api/event/9044?api_key=APP_KEY

Response: (portions truncated)

<?xml version="1.0" encoding="UTF-8"?>
<event>
  <id>9044</id>
  <title>WordCamp Mid-Atlantic</title>
  <description>WordPress is now...</description>
  <type>Technology</type>
  <keywords type="array">
    <keyword type="hashtag">#wordcampmidatl</keyword>
  </keywords>
  <url>http://wordcampmidatlantic.eventbrite.com/</url>
  <organizer>Localist</organizer>
  <last_modified>2009-05-11T20:14:47Z</last_modified>
  <geo>
    <location>University of Baltimore Thumel Business Center</location>
    <latitude>39.305246</latitude>
    <longitude>-76.616582</longitude>
    <street_1>11 W Mt Royal Ave</street_1>
    <locality>Baltimore</locality>
    <region>MD</region>
    <country>US</country>
    <zip>21201</zip>
  </geo>
  <city_id>1</city_id>
  <neighborhood_id>5</neighborhood_id>
  <event_instances type="array">
    <event_instance>
      <id>25256</id>
      <event_id>9044</event_id>
      <start>2009-05-16T08:00:00Z</start>
      <end>2009-05-16T17:00:00Z</end>
      <class>Public</class>
      <ticket_info>http://wordcampmidatlantic.eventbrite.com/</ticket_info>
      <ticket_price>$25 for admission...</ticket_price>
      <age_requirement>0</age_requirement>
      <ranking>19</ranking>
    </event_instance>
  </event_instances>
  <localist_url>http://www.localist.com/...</localist_url>
  <photo_url>http://images.localist.com/...</photo_url>
</event>

Get Event Reviews

Method: /event/event_id/reviews/

Returns the reviews of the venue specified by venue_id.

A list of <review> elements will be returned in the <reviews> element. A <meta> element will also be returned with details about total review count and paging.

Parameters	Description
`api_key`	Required, the application key
`pp`	Number of reviews to return (1-50, defaults to 10)
`page`	Page number of results (defaults to 1, counts from 1)

Example request: http://www.localist.com/api/event/3336/reviews?pp=10&page=1&api_key=APP_KEY

Response: (portions truncated)

<?xml version="1.0" encoding="UTF-8"?>
<reviews>
  <review>
    <id>182</id>
    <rating>0</rating>
    <comment>Took the Baltimore Metro...</comment>
    <review_of>event</review_of>
    <event_id>3336</event_id>
    <event_date>2008-07-19</event_date>
    <created_at>2008-08-14T04:12:39Z</created_at>
    <updated_at>2008-08-14T04:12:39Z</updated_at>
    <reviewer_id>2</reviewer_id>
    <reviewer_username>nate</reviewer_username>
    <reviewer>Nate</reviewer>
  </review>
  <!-- truncated ... -->
  <meta>
    <page>1</page>
    <pp>10</pp>
    <num_pages>1</num_pages>
  </meta>
</reviews>

Get Top Rated Events

Method: City: /city/city_id/top_events
Neighborhood: /city/city_id/neighborhood/neighborhood_id/top_events

Returns a listing of top-rated events for a specified date range in the city city_id, or in the neighborhood identified by city_id, neighborhood_id.

For events in a city, use the first form of the method; for a single neighborhood, use the second form.

The events will be returned in the <events> element, ordered by descending ranking. Note that rankings are attached to event instances, and each returned event will only contain the appropriate instance.

Parameters	Description
`api_key`	Required, the application key
`num`	Number of events to return (1-50, default 10)
`days`	Number of future days to consider (1-30, default 5)

Example city request: http://www.localist.com/api/city/1/top_events?num=10&days=5&api_key=APP_KEY

Example neighborhood request: http://www.localist.com/api/city/1/neighborhood/1/top_events?num=10&days=5&api_key=APP_KEY

Response: (portions truncated)

<events type="array">
  <event>
    <id>11252</id>
    <title>The Shins</title>
    <description>For The Shins...</description>
    <type>Concert/DJ</type>
    <genre>Indie</genre>
    <keywords type="array">
      <keyword type="hashtag">the_shins</keyword>
    </keywords>
    <url>http://www.theshins.com</url>
    <organizer>Localist</organizer>
    <last_modified>2009-04-16T19:11:41Z</last_modified>
    <geo>
      <location>Rams Head Live!</location>
      <location_id>42</location_id>
      <latitude>39.288289</latitude>
      <longitude>-76.606923</longitude>
      <street_1>20 Market Pl</street_1>
      <locality>Baltimore</locality>
      <region>MD</region>
      <country>US</country>
      <zip>21202</zip>
    </geo>
    <city_id>1</city_id>
    <neighborhood_id>4</neighborhood_id>
    <event_instances type="array">
      <event_instance>
        <id>32472</id>
        <event_id>11252</event_id>
        <start>2009-05-15T19:30:00Z</start>
        <class>Public</class>
        <ticket_info>http://tickets.ramsheadlive.com/...</ticket_info>
        <ticket_price>$35</ticket_price>
        <age_requirement>0</age_requirement>
        <ranking>9</ranking>
      </event_instance>
    </event_instances>
    <localist_url>http://www.localist.com/...</localist_url>
    <photo_url>http://images.localist.com/...</photo_url>
  </event>
  <!-- truncated ... -->
</events>