API Documentation

The Gravy API supports the retrieval of events and event data in several different ways. Lists of events can be retrieved by mood, category, venue or channel. Additional detail data about an event can also be retrieved.In each of these cases something must first be known: the identifier specific to a particular mood, category, venue or channel. These identifiers are retrieved or discovered in different ways. The set of moods can be retrieved via the /moods web service and can also be easily found in the example response provided for the service. Categories and their identifiers are included in this documentation. One way to retrieve venue identifiers is to use the venue ids returned for events returned in other event list responses, for example a mood or category based request. The set of active channels can be retrieved by a request to the /channels web service. Finally, the web service responses which contain lists of events also contain the event identifier which can be used to retrieve additional event details.

The Gravy event management system publishes events for approximately 30 days out from the current date, constantly adding new events as existing events move into the past. Searching for events more than 30 days into the future may result in sparse or empty results being returned. In addition, events may cease to exist once their start dates have moved into the past

The Gravy API is available in both a test environment and a production environment. You will require a different API key for each environment.

Environment URL Base
Test https://api.foozor.com/v1/
Production https://api.findgravy.com/v1/

Responses

The Gravy API formats responses using either JSON or XML. The response format can be specified either by using an extension in the request URL (i.e. /events.json or /events.xml) or by setting the 'Accept' header (i.e. application/json or application/xml). Specifying an extension will take precedence over setting the 'Accept' header.

Status Codes

Before attempting to parse a response from the Gravy API, the HTTP response status code should be examined. A status code of 200 means that the request completed successfully. All other status code values mean that there was a problem processing the request.

Status Code Description
200 Indicates that the supplied request was processed without a failure but does not guarantee that results will be returned. For instance, your search criteria may have resulted in no events being found.
400 Indicates that the supplied request was not valid. The most likely causes are a missing parameter, an illegal value for a parameter, or an improperly formatted 'Authorization' header.
403 Indicates that the supplied request did not contain a valid API key.
404 Indicates that the supplied request was for a non-existent URL. This will happen when attempting to retrieve the event details for an event that has ceased to exist.
500 Indicates that the supplied request resulted in an error on the server.

API Key

In order to make requests using the Gravy API, a valid API key must be set in the 'Authorization' header of the request. Please contact your Gravy representative to obtain an API key. The value of the 'Authorization' should be 'Gravy apiKey="API KEY HERE"'. A sample header is shown below:

Authorization: Gravy apiKey="d01fcfbf-9685-44c0-9a34-b750a6e5f224"

Available Requests

Parameter Data

The parameter names to be passed to the requests are case-sensitive.

/moods

Retrieves a list of available moods.

/events

Retrieves a list of events using the parameters supplied in the request. There are three query types supported by this web service: by mood, by category and by venue.

Name Description Sample Value Notes
moodId The mood identifier to use. The value should be obtained from a call to /moods. 1 Either the moodId, categoryId or venueId parameter is required. If multiple query parameters are provided,the precedence is first venueId, then categoryId and then moodId.
categoryId The category identifier to use. 100 The use of this parameter is mutually exclusive with queries by mood or venue. List of Categories is here
fromDate The date from which to start searching for events. 2013-03-01T17:00:00-05:00 This parameter is required and must use a valid date/time as defined by ISO 8601.
toDate The date to use to stop searching for events. The value of this parameter must be within 30 days of 'from date' when filtering by venue and 7 days when filtering by moodId or categoryId. 2013-03-03T22:00:00-05:00 This parameter is required and must use a valid date/time as defined by ISO 8601.
timeZone The time zone identifier associated with the fromDate and toDate parameters. America/New_York This parameter is required and must use the Olson format.
latitude The latitude value to use when searching for events. 39.090700 This parameter is required when searching using a mood query (moodId) or category query (categoryId). This parameter should not be specified when using a venue identifier.
longitude The longitude value to use when searching for events. -77.525754 This parameter is required when searching using a mood query (moodId) or category query (categoryId). This parameter should not be specified when using a venue identifier.
deviceLatitude The current latitude of the device making request. This value will be used to calculate the distance to the events being returned. 39.090700 This parameter is optional.
deviceLongitude The current longitude of the device making request. This value will be used to calculate the distance to the events being returned. -77.525754 This parameter is optional.
venueId The venue identifier to use to search for events. 1001 Either the moodId, categoryId or venueId parameter is required. If multiple query parameters are provided, the precedence is first venueId, then categoryId and then moodId.
radius Specifies how close events should be to the supplied latitude and longitude. 10.0 This parameter is currently not supported and should not be supplied in the request.
maxExperiences The maximum number of events to return. 100 This parameter is optional and will default to 20. It will only be used when searching using a mood identifier.
priority Specifies how to sort the events being returned. Possible values are SCORE and DISTANCE. SCORE This parameter is optional and will default to SCORE. It will only be used when searching using a mood identifier.

/events/wideDate

This call requires specific privillages to be used.
Functionally similar to '/events', but instead allows the retrieval of events with a 30 day date range. Extra data is also returned in the response. Retrieves a list of events using the parameters supplied in the request. There are three query types supported by this web service: by mood, by category and by venue.

Name Description Sample Value Notes
moodId The mood identifier to use. The value should be obtained from a call to /moods. 1 Either the moodId, categoryId or venueId parameter is required. If multiple query parameters are provided,the precedence is first venueId, then categoryId and then moodId.
categoryId The category identifier to use. 100 The use of this parameter is mutually exclusive with queries by mood or venue. List of Categories is here
fromDate The date from which to start searching for events. 2013-03-01T17:00:00-05:00 This parameter is required and must use a valid date/time as defined by ISO 8601.
toDate The date to use to stop searching for events. The value of this parameter must be within 30 days of 'from date' when filtering by venue and 7 days when filtering by moodId or categoryId. 2013-03-03T22:00:00-05:00 This parameter is required and must use a valid date/time as defined by ISO 8601.
timeZone The time zone identifier associated with the fromDate and toDate parameters. America/New_York This parameter is required and must use the Olson format.
latitude The latitude value to use when searching for events. 39.090700 This parameter is required when searching using a mood query (moodId) or category query (categoryId). This parameter should not be specified when using a venue identifier.
longitude The longitude value to use when searching for events. -77.525754 This parameter is required when searching using a mood query (moodId) or category query (categoryId). This parameter should not be specified when using a venue identifier.
deviceLatitude The current latitude of the device making request. This value will be used to calculate the distance to the events being returned. 39.090700 This parameter is optional.
deviceLongitude The current longitude of the device making request. This value will be used to calculate the distance to the events being returned. -77.525754 This parameter is optional.
venueId The venue identifier to use to search for events. 1001 Either the moodId, categoryId or venueId parameter is required. If multiple query parameters are provided, the precedence is first venueId, then categoryId and then moodId.
radius Specifies how close events should be to the supplied latitude and longitude. 10.0 This parameter is currently not supported and should not be supplied in the request.
maxExperiences The maximum number of events to return. 100 This parameter is optional and will default to 20. It will only be used when searching using a mood identifier.
priority Specifies how to sort the events being returned. Possible values are SCORE and DISTANCE. SCORE This parameter is optional and will default to SCORE. It will only be used when searching using a mood identifier.

/events/artists

Retrieves a list of events using the parameters supplied in the request and the listed artist names.

Name Description Sample Value Notes
fromDate The date from which to start searching for events. 2013-03-01T17:00:00-05:00 This parameter is required and must use a valid date/time as defined by ISO 8601.
toDate The date to use to stop searching for events. 2013-03-03T22:00:00-05:00 This parameter is required and must use a valid date/time as defined by ISO 8601.
latitude The latitude value to use when searching for events. 39.090700 This parameter is required.
longitude The longitude value to use when searching for events. -77.525754 This parameter is required.
radius Specifies how close events should be to the supplied latitude and longitude. 1.2 This parameter is optional and is limited from 0.0 to 4.3 inclusive.
maxExperiences The maximum number of events to return. 100 This parameter is optional and will default to 20. It will only be used when searching using a mood identifier.
artist The exact name of an artist to search for. The Chee Weez This parameter is required and used to indicate a artist name to search for. A maximum of 8 artist names are read in. Parameter is not case sensitive but all artist identifiers must have the same case. Ex: "artist" vs. "Artist" vs. "arTist".

/events/DMA/:location

The /events/DMA/:location web service returns a list in rss form of events centered on the location.

Name Description Sample Value Notes
location The name of the search location. washingtonDC This parameter is required.

Locations

List of currently supported locations for /events/DMA/:location

location display namedescription
washingtonDC Washington DC DMAWashington including the Maryland & Virginia close in suburbs
atlanta Atlanta DMAAtlanta including close in suburbs
detroit Detroit DMADetroit including close in suburbs
miami Miami DMAMiami including close in suburbs

/moodEvents

Retrieves a list of events for a Mood using the parameters supplied in the request.There are two query types supported by this web service: by mood and by category.

Name Description Sample Value Notes
moodId The mood identifier to use. The value should be obtained from a call to /moods. 1 Either the moodId or categoryId parameter is required. If both are specified, then the categoryId parameter will take precedence.
categoryId The category identifier to use. 100 This parameter is optional. List of Categories is here
fromDate The date from which to start searching for events. 2013-03-01T17:00:00-05:00 This parameter is required and must use a valid date/time as defined by ISO 8601.
toDate The date to use to stop searching for events. The value of this parameter must be within 7 days of 'from date'. 2013-03-03T22:00:00-05:00 This parameter is required and must use a valid date/time as defined by ISO 8601.
timeZone The time zone identifier associated with the fromDate and toDate parameters. America/New_York This parameter is required and must use the Olson format.
latitude The latitude value to use when searching for events. 39.090700 This parameter is required when searching using a mood identifier. This parameter should not appear when using a venue identifier.
longitude The longitude value to use when searching for events. -77.525754 This parameter is required when searching using a mood identifier. This parameter should not appear when using a venue identifier.
deviceLatitude The current latitude of the device making request. This value will be used to calculate the distance to the events being returned. 39.090700 This parameter is optional.
deviceLongitude The current longitude of the device making request. This value will be used to calculate the distance to the events being returned. -77.525754 This parameter is optional.
maxExperiences The maximum number of events to return. 100 This parameter is optional and will default to a internal system parameter value which is currently 20.
priority Specifies how to sort the events being returned. Possible values are SCORE and DISTANCE. SCORE This parameter is optional and will default to SCORE. It will only be used when searching using a mood identifier

/venueEvents

Retrieves a list of events for a venue using the parameters supplied in the request.

Name Description Sample Value Notes
venueId The venue identifier to use to search for events. 1001 This parameter is required.
fromDate The date from which to start searching for events. 2013-03-01T17:00:00-05:00 This parameter is required and must use a valid date/time as defined by ISO 8601.
toDate The date to use to stop searching for events. The value of this parameter must be within 30 days of 'from date'. 2013-03-03T22:00:00-05:00 This parameter is required and must use a valid date/time as defined by ISO 8601.
timeZone The time zone identifier associated with the fromDate and toDate parameters. America/New_York This parameter is required and must use the Olson format.
deviceLatitude The current latitude of the device making request. This value will be used to calculate the distance to the events being returned. 39.090700 This parameter is optional.
deviceLongitude The current longitude of the device making request. This value will be used to calculate the distance to the events being returned. -77.525754 This parameter is optional.
radius Specifies how close events should be to the supplied latitude and longitude. 10.0 This parameter is currently not supported and should not be supplied in the request.
maxExperiences The maximum number of events to return. 100 This parameter is optional and will default to 20. It will only be used when searching using a mood identifier.
priority Specifies how to sort the events being returned. Possible values are SCORE and DISTANCE. SCORE This parameter is optional and will default to SCORE. It will only be used when searching using a mood identifier.

/event/:eventId

Retrieves the details of a specific event.

Name Description Sample Value Notes
latitude The latitude value to use to calculate the distance to the event. 39.090700 This parameter is optional.
longitude The longitude value to use to calculate the distance to the event. -77.525754 This parameter is optional.

/channels

The /channels web service will return the set of active channels within the Gravy system and attributes about each channel. However, information on the current hierarchy of groups of channels in Gravy is not provided through this web service call. If the hierarchical group structure is important, please use the /channels/channelHierarchy web service. To retrieve only the channels related to a specific group, such as the “Featured” channels group, the channelGroupId can be specified as a parameter. The channelGroupId 1 will always return the set of currently featured channels.

Name Description Sample Value Notes
excludeSubscribedCampaigns The campaigns the user is subscribed to are filtered out. 1 This parameter is optional.
channelGroupId The campaigns are filtered by the channelGroupId. 1 This parameter is optional.

/channelsHierarchy

The /channels/channelHieararchy web service returns a result set of active channels within the Gravy system and their properties. channelHiearchy adds the current hierarchical definition of groups within Gravy but otherwise is the same as the /channels web service.. To retrieve only the channels related to a specific group, such as the “Featured” channels group, the channelGroupId can be specified as a parameter.

Name Description Sample Value Notes
excludeSubscribedCampaigns The campaigns the user is subscribed to are filtered out. 1 This parameter is optional.
channelGroupId The campaigns are filtered by the channelGroupId. 1 This parameter is optional.

/channel/:channelId

The /channel web service returns the set of events for a given channel based on the channelId, latitude and longitude passed as parameters.

Name Description Sample Value Notes
latitude The latitude value to use to calculate the distance to the event. 39.090700 This parameter is required.
longitude The longitude value to use to calculate the distance to the event. -77.525754 This parameter is required.
maxExperiences The maximum number of events to return. 100 This parameter is optional.

/channel/RSS/:channelId

The /channel/RSS/ web service returns the set of events in RSS format for a given channel based on the channelId, latitude and longitude passed as parameters.

Name Description Sample Value Notes
latitude The latitude value to use to calculate the distance to the event. 39.090700 This parameter is required.
longitude The longitude value to use to calculate the distance to the event. -77.525754 This parameter is required.
maxExperiences The maximum number of events to return. 100 This parameter is optional.

/subscribe

The /subscribe web service subscribes an email address to a channel.

Name Description Sample Value Notes
email The email address for subscription to a channel. 1 This parameter is required.
channelId The channelId the email address needs to be subscribed to. 1 This parameter is required.

/popular

Returns a list of events. This list of events lists events with larger numbers of likes, saves, and other values indicating that an event is popular among users. These events are centered around a griven point.

Name Description Sample Value Notes
latitude Latitude for the location to search for events around 38.897297 This parameter is required.
longitude Longitude for the location to search for events around. -77.020935 This parameter is required.
startDate Minimum date to find events for. 1388778239000 This parameter is required.

Categories

The Category Ids

categoryId Name parentCategoryId
8 Music
9 Concerts & Tour Dates 8
10 Festivals (Music) 8
11 Fundraising & Charity (Music) 8
12 Neighborhood (Music) 8
13 Jazz 8
14 Folk and Bluegrass 8
15 Rock 8
16 Speed Metal 8
17 Country 8
18 Blues 8
19 Alternative 8
20 Popular 8
21 Gospel 8
22 Ethnic 8
23 Chamber Music / Quartets 8
24 Classical 8
25 Symphony 8
26 School Concerts 8
27 Religious not Gospel 8
28 Acapella / Barber Shop 8
29 Military / Martial / Marching 8
30 Business
31 Conferences & Tradeshows 30
32 Business & Networking 30
33 Technology 30
34 Education
35 Nightlife
36 Family
37 Festivals (Family) 36
38 Fundraising & Charity (Family) 36
39 Fairs 36
40 Crafts 36
41 Children's Events 36
42 Storytelling 36
43 Holiday 36
44 Cleanup Parties 36
45 Safety 36
46 Financial Planning 36
47 Pets
48 Military 153
49 Arts
50 Festivals (Arts) 49
51 Fundraising & Charity (Arts) 49
52 Literary & Books 49
53 Museums & Attractions 49
54 Neighborhood (Arts) 49
55 Food & Beverage
56 Festivals (Food & Beverage) 55
57 Fundraising & Charity (Food & Beverage) 55
58 Sports
59 Festivals (Sports) 58
60 Fundraising & Charity (Sports) 58
61 Neighborhood (Sports) 58
62 Outdoors & Recreation 87
63 Hobbies
64 Organizations & Meetups 63
65 Science 63
66 Politics & Activism
67 Health & Wellness
68 School
69 University & Alumni 68
70 Sales & Retail
71 Religion & Spirituality
73 Performing Arts 49
74 Film 49
75 Comedy 49
76 Neighborhood 36
77 Tourism
78 Poker 63
79 Hip Hop & Rap 8
80 Tournament 58
81 LGBT 66
82 LGBT (Nightlife) 35
83 Nature 87
84 Brunch 55
85 Wine Tasting 55
86 Auto 63
87 Nature & Outdoors
88 Fashion
89 Basketball 58
90 Classical Theater 49
91 Ice Hockey 58
92 Contemporary Theater 49
93 Soccer 58
94 Children's Theater 36
95 World Music Concerts 8
96 Concerts - R&B, Soul & Funk 8
97 DJ and Music 35
98 Opera 49
99 Indie Rock 8
100 Running Event 58
101 Self Help 34
102 Circus 36
103 80s 8
104 Disco 8
105 Professional Baseball 58
106 Professional Football 58
107 Professional Basketball 58
108 Jam Bands 8
109 Cover Bands 8
110 Volunteer 66
111 Disabled 66
112 Minor League Football 58
114 Tennis 58
115 Contest / Submissions 36
116 Latin 8
117 Cabaret 49
118 Carnivals 36
119 Football (US) 58
120 Baseball 58
143 Happy Hour
146 Gallery Events 49
148 Friends Gatherings
149 Reggae 8
150 Bluegrass and Folk 8
151 Community - Workshops
152 Mom Activities 36
153 Unique Ideas
154 Photography 63
155 Ticketfly
156 Restaurant Promotion 55
157 Other
158 Farmers Markets 55
159 Aerial 153
160 Halloween
161 Boardgames 63
162 Motorsports 58
163 Dance 63
164 Martial Arts 58
165 Belly Dancing 35
166 Yoga 67
167 Alternative Health 67
168 Dogs 47
169 Witches 63
170 Movies -- Lively
171 Movies -- Playtime
172 Movies -- Classy
173 Movies -- Brainy