EvieSays API v1.1

Obtaining an API Key

Use of the EvieSays API requires a valid API Key, which is available for EvieSays customers only.  Please contact our sales department if you are interested in using the EvieSays API.

Your API Key

Log in to view your API key.

Your API key is exclusive to your account. Do not share your API key with anyone.

Calling the API

Currently, all functions of the EvieSays 1.1 API are GET commands that return JSON text.  The format for queries is:

https://api.eviesays.com/1.1/[function].json?api_key=[your API key]&[search parameters]

Functions

getEvents

Overview

getEvents returns a list of individual occurrences of events within a search area, which is defined by a point (coordinates) and a distance (a radius from that point in statute miles, defining a circle on the Earth). Typically, your API key will automatically use the search area defined by the site to which the key is assigned. Additional parameters can be used to filter the result set.

Return Value

getEvents returns an object with the following keys:

events
An array of event objects
total_found
The total number of events matching the query. If this number is greater than the number of events contained within the "events" array, then you can request the remainder using offset and limit parameters.

Optional Parameters

Pagination

By default, Evie will return up to 500 records. To obtain more, you must perform another query.

limit
The maximum number of events to return in the query (default and max: 500)
offset
For queries resulting in more than the maximum number of events, this defines the offset for the next batch.
Time Filters
start_date
A date defining the start point for events (format: YYYY-MM-DD, default: the current date)
end_date
A date defining the end point for events (format: YYYY-MM-DD, default: the current date)
time_zone
An IANA tzdata-style time zone definition (i.e. "America/New_York"). This is required and only used when filtering by start_date and/or end_date to establish the proper time for those filters. The start and end times of the events in the results are based on the time zone of their venue's location.
Keyword Filters
q
A keyword search. By default it is a natural language search, though explicit tag and date definition will override any matching keywords and it will result to an event title search.
tags
A JSON array of strings with each string representing a category/tag (i.e. ["Sports"]). The exact tag set is determined by the site. A logical OR operation is used for multiple tags.
Location Filters

Though the search area must be defined by a point (latitude and longitude) and distance (radius around the point in statute miles), the results can be filtered by the following criteria. This is particularly useful when trying to filter event in densely populated areas.

postal_code
A JSON array of one or more codes. Example: ["10001","10002"].
state
A JSON array of one or more state codes. Example: ["NY","NJ"]
city
A JSON array of one or more city names. Example: ["New York"]
Other Filters
venue_id
A single venue ID, or JSON array of one or more venue IDs (likely obtained from another query). If defined, getEvents will limit the resulting events to only those occurring at the given venue(s). Example: ["33546","33552"]

Examples

Return the first 250 events tagged with Comedy, Music, or Sports within 50 miles of San Francisco, CA:

https://api.eviesays.com/1.1/getEvents.json?api_key=MYAPIKEY&latitude=37.7833&longitude=-122.4167&distance=50&limit=250&tags=["Comedy","Music","Sports"]

Return all events within 25 miles of 40.7127° N, 74.0059° W (New York City, NY), but only those occurring within the state of New York:

https://api.eviesays.com/1.1/getEvents.json?api_key=MYAPIKEY&latitude=40.7127&longitude=-74.0059&distance=25&state=["NY"]

getEvent

Overview

getEvent returns details on one event.

Return Value

getEvent returns an object with the following keys:

event
the detailed data for the event, including all times associated with the event.

Required Parameters

getEvent must know which event you are referring to. For that, simply give it the event ID (likely obtained from a previous call to another function).

id
The unique event ID.

Examples

Return the details for event with ID 6789898 ("Basic Beginnings: Growing Together" in Bismarck, ND)

https://api.eviesays.com/1.1/getEvent.json?api_key=MYAPIKEY&id=6789898

getVenues

Overview

getVenues returns a list of venues. You must specify a search area, which is defined by a point (coordinates) and a distance (a radius from that point in statute miles, defining a circle on the Earth). getVenues will then return data for venues located within the defined area. Additional parameters can be used to filter the result set.

Required Parameters

latitude
The latitude coordinate of the search center's point in decimal degrees.
longitude
The longitude coordinate of the search center's point in decimal degrees.
distance
The radius, in statute miles, defining the search area around the given point.

Optional Parameters

Pagination

By default, Evie will return up to 500 records. To obtain more, you must perform another query.

limit
The maximum number of venues to return in the query (default and max: 500)
offset
For queries resulting in more than the maximum number of venues, this defines the offset for the next batch.
Keyword Filters
q
A keyword search. By default it is a natural language search, though explicit tag and date definition will override any matching keywords and it will result to an event title search.
Location Filters

Though the search area must be defined by a point (latitude and longitude) and distance (radius around the point in statute miles), the results can be filtered by the following criteria:

postal_code
A single postal or zip code, or JSON array of one or more codes. Example: ["10001","10002"].
state
A single state code or JSON array of one or more state codes. Example: ["CA","OR"]

Examples

Return venues (up to a maximum of 500) located within 25 miles of 36.1° N, 86.7° W (Nashville, TN):

https://api.eviesays.com/1.1/getVenues.json?api_key=MYAPIKEY&latitude=36.1&longitude=-86.7&distance=25

Return venues (up to a maximum of 500) located within 25 miles of 36.1° N, 86.7° W (Nashville, TN) with a keyword of "Blue":

https://api.eviesays.com/1.1/getVenues.json?api_key=MYAPIKEY&latitude=36.1&longitude=-86.7&distance=25&q=Blue

getVenue

Overview

getVenue returns details on one venue.

Return Value

getVenue returns an object with the following keys:

venue
the detailed data for the venue

Required Parameters

getVenue must know which venue you are referring to. For that, simply give it the venue ID (likely obtained from a previous call to another function).

id
The unique venue ID.

Examples

Return the details for venue with ID 1065649 (Bluebird Cafe in Nashville, TN)

https://api.eviesays.com/1.1/getVenue.json?api_key=MYAPIKEY&id=1065649