API Method /venues/get

Given a venue ID, returns information about that particular venue.

Arguments

authentication: This method requires the usual authentication arguments.
id string: The id of the requested venue.
mature string: Sets the level of filtering for events marked as "mature" due to keywords in the title or description. One of 'all' (no filtering), 'normal', or 'safe'. 'Normal' mature filtering consists of words that are clearly profanities and inappropriate for younger audiences. 'Safe' mature filtering consists of all normal mature filtered words, as well as other terms that may be used as inappropriate innuendo. A 'safe' filter may eliminate events that are benign in nature, but contain questionable content based on keywords. Defaults to 'all'. (optional)

Example Request

Here's an example request URL:

http://api.eventful.com/rest/venues/get?...&id=V0-001-000104270-1

Output Parameters

Output from this function is an XML block with the following constructs:

id string

The unique ID for this event. Presented as an object attribute. See the example below.

url string

The page URL for this venue on eventful.com.

name string

The name of the venue.

description string

The venue description.

venue_type string

The type of venue (Arena, Restaurant, Park, etc.)

venue_display boolean

Whether or not the venue name should be displayed in certain cirumstances. Eventful's notion of a venue is a bit broader than you might think. For example, events for which only the postal code is known have a venue named "Postal code 46311, US", for instance. In these cases, a traditional address block looks a bit unusual, and Eventful chooses not to display the venue name in these cases. You may wish to do the same, and the venue_display parameter allows you to do that.

address string

The venue's street address.

city string

The city where the venue is located.

region string

The region where the venue is located. A "region" is an Eventful general term for sub-country political divisions like States, Provinces, Cantons, etc.

postal_code string

The postal code for the venue.

country string

The country name for the venue.

latitude signed float

The venue latitude.

longitude signed float

The venue longitude.

geocode_type string

The method used to geocode the venue latitude and longitude.

created string

A time stamp in ISO 8601 format (e.g. "2005-03-01 19:00:00") indicating when this venue was created.

owner string

The Eventful user name of the user who created this venue.

withdrawn boolean

Indicates whether this venue has been "withdrawn" or not. "1" indicates TRUE, "0" indicates FALSE.

withdrawn_note string

A note indicating why the venue has been withdrawn. (e.g. "Closed",

parent_id string

The ID of this venue's immediate parent. This duplicates information from the parents array (below) to some extent, but it's useful nonetheless.

parents array

An array of records showing the entire chain of parents of this venue. The first parent is the venues's immediate parent, the next is its grandparent, and so on.

id string: The unique ID of the parent venue.
name string: The name of the parent venue.

children array

An array of records showing any child venues associated with this venue. Unlike parents, only the immediate children of this venue are shown (i.e. no grandchildren).

id string: The unique ID of the child venue.
name string: The name of the child venue.
description string: The description of the child venue.

events array

A list of the next few upcoming events at this venue.

id string: The unique ID of the event.
title string: The event title.
start_time string: The event start time in ISO 8601 format (e.g. "2005-03-01 19:00:00")
stop_time string: The event stop time in ISO 8601 format (e.g. "2005-03-01 19:00:00")
description string: The event description.

links

A list of links associated with the event. Each link entry has the following structure:

id integer: Link id + the Event id is the uniq identifer for a link.
type string: The URL type string.
user string: User Name that owns this link
description string: The URL description.
url string: The "linked" text (i.e. the stuff between <a> and </a>).
time string: Time the Link was added in ISO 8601 format (e.g. "2005-03-01 19:00:00")

comments

A list of comments associated with the event. Each comment entry has the following structure:

id integer: Comment id + the Event id is the uniq identifer for a Comment.
text string: The text of the comment.
user string: The user name of the user who posted the comment.
time string: The time the user submitted the comment. in ISO 8601 format (e.g. "2005-03-01 19:00:00")

trackbacks

A list of trackback URLs associated with the event. Each trackback entry has the following structure:

id integer: Trackback id + the Event id is the uniq identifer for a Trackback.
blog_name string: The name of the website the trackback is from.
trackback_url string: The URL of the website the trackback is from.
excerpt string: The comment associated with the trackback.
time string: The timestamp when we received the trackback in ISO 8601 format (e.g. "2005-03-01 19:00:00")

images

A list of images associated with the event. Each images entry has the following structure:

id integer: Image id + the Event id is the uniq identifer for a Image
url string: The image URL.
width integer: The image width, in pixels.
height integer: The image height, in pixels.
caption string: The image caption. A short description of the image.

tags

A list of tags associated with the event. Each link entry has the following structure:

stringstring: The tag string itself.
user string: Thei username who created this tag

properties

A list of properties for the event. Each property entry has the following structure:

idinteger: The ID of this property (used when removing).
namestring: The name of this property.
valuestring: The value of this property.

Example XML Response


<venue id="V0-001-000147640-3">
  <url>http://eventful.com/venues/san-diego/petco-park-/V0-001-000147640-3
  ?utm_source=apis&utm_medium=apim&utm_campaign=apic
  </url>
  <name>Petco Park</name>
  <description>The home of the San Diego Padres baseball team.</description>
  <venue_type>Stadium</venue_type>
  <venue_display>1</venue_display>
  <address>100 Park Boulevard</address>
  <city>San Diego</city>
  <region>California</region>
  <postal_code>92101</postal_code>
  <country>United States</country>
  <created>2005-05-27 12:33:02.536316</created>
  <owner>chuck</owner>
  <withdrawn>0</withdrawn>
  <withdrawn_note/>
  <parent_id/>
  <parents/>
  <children/>
  <events>
    <event id="E0-001-000195479-8">
      <title>Seattle Mariners at San Diego Padres</title>
      <start_time>2005-06-24 19:05:00</start_time>
      <stop_time/>
      <description/>
    </event>
    <event id="E0-001-000195613-0">
      <title>Seattle Mariners at San Diego Padres</title>
      <start_time>2005-06-25 13:10:00</start_time>
      <stop_time/>
      <description/>
    </event>
    <event id="E0-001-000195677-8">
      <title>Seattle Mariners at San Diego Padres</title>
      <start_time>2005-06-26 13:05:00</start_time>
      <stop_time/>
      <description/>
    </event>
  </events>
  <links/>
  <comments/>
  <trackbacks/>
  <images/>
  <tags>
    <tag id="petcopark">
      <title>PetcoPark</title>
      <owner>chuck</owner>
    </tag>
    <tag id="petcoparktickets">
      <title>Petco Park tickets</title>
      <owner>evdb</owner>
    </tag>
  </tags>
  <properties>
    <property>
      <id>123</id>
      <name>Rating</name>
      <value>5 stars</value>
    </property>
  </properties>
</venue>

Error Codes

This method may return these errors in an error document:

Authentication error: The specified user was not found or provided invalid credentials.
Missing parameter: A mandatory parameter was not set.
Not found: There is no venue with that identifier.

Eventful API

Overview

Tools

Technical Reference