Technical Reference

Wise words

FAQ

Code Sample

Where can I see an example of the API being used?

You can run this javascript sample in your web browser while seeing the source code by clicking here
You can also check out the source of the different API libraries by looking here or our github account here

Time Zones

What time zone is start/stop time in?

The start_time and stop_time fields are provided in "floating" time, which should be interpreted as "the time appropriate for the venue." In most cases the times are from local event sites or promoters, so the time zone is not provided. We don't make any guesses about the time zone, because the "floating" time is exactly what a local would expect. All other times (created, modified, etc.) are in Pacific time.

Category Info

How do I get category information for events?

To include category information in the search results you need to add &include=categories to your query string parameters.

HTTPS

How do I get secure urls to images or other eventful objects back from the API?

Most API search calls have been updated to accept a query string parameter of scheme. The current default is "http" so any image url or link to an Eventful event,performer or venue will be returned as http. If you would prefer https links to be returned then adding &scheme=https will do that. Schemeless urls of the form //url can also be returned if &scheme=none is used. At some point in the future after the entire Eventful website has been transitioned to https the default will be switched to https.

Recurrence and long duration events

Why do I get events out side my search date range?

There are 2 reasons that an event with a start_date outside of the date range you pick can show up in your results. The first is that the start_date is for example last week but the end date is 2 weeks from now. An art show that is showing for 3 weeks would be an example of this type of event. Even though the start_date is last week and you for example specify the date range of tomorrow through the end of the week you would see this event since it is still going on during the time frame you specify even though the start date is before. We do offer a search query string parameter of after_start_date that will exclude these type of events if you want to use it. Just set that date to the same as your start date in the date range and then those events will be excluded.
&nbsp The other reason an event may show up in your results is if it repeats and one of the occurrences is during your range. You can add &include=instances to your query string to get all the instance data back from the query and then you will be able to see that the event does occur during your date range and will be given the instances of the recurrence.
You can also use the change_multi_day_start parameter to which will set the start_date to the next occurrence after the date you specify istead of the first one. See /events/search for details on change_multi_day_start.

JSON Response

OAuth Authentication, do I need it?

Do I even need OAuth? Do I need each of my app users to authorize Eventful?

It depends on your app. If you are just querying for events all you need is a valid app_key to be able to do an event search. If you want your app to make any calls that say user authentication is required you will need Oauth. If you want each of your app users to have access to their eventful user profile you'll need to setup oauth for each of them, but if you only need a generic user to make calls then just one Oauth setup will work. For example creating a new event requires Oauth. If you want each user of your app to have their own events then you would need them each to use Oauth to authorize their eventful account to use your app. If on the other hand you just need to allow them to create events and all the events will be owned by the single app user tied to your app key then one Oauth authorization is good enough.

Oauth Parameters

OAuth - where do the oauth parameters go?

You can place your oauth parameters in any of the following places.

The query string of the request url, each parameter would be separated by a &.

Part of the POSTed data. Each parameter should be separated by a & just like it was part of the query string.

As part of the HTTP headers in the Authorization line. Example:
Authorization: OAuth oauth_callback="http%3A%2F%2Fexample.com%2Foauth_callback.php", oauth_consumer_key="key", oauth_nonce="nonce", oauth_signature="sig", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1365662208", oauth_version="1.0"

Oauth Cold Fusion example

OAuth and ColdFusion, do they work together?

Thanks to Brian Ghidinelli there is a sample Cold Fusion api library that supports most of the event and venue functions and it can be found here Not every api function is supported but it is a good place to start.
Some simple sample code can also be found here

Problems Using Oauth

How do I get my oauth request to not return a 404?

There are a few common errors when an oauth request is constructed. Please make sure your are making the request via the correct POST or GET method, and all paramaters are being used when the oauth signature is being computed. You should then check the signautre you are passing over to what is computed by entering the parameters here (When making the first call to get the request token leave token and token secret empty in the form).Remember to add in a field for app_key when that is passed in. Most of the time the signature will not match due to not all arguments being put into the signature, wrong method, etc.

I still cant get Oauth to work

Is there any help if I still get a 404?

You can send a test Oauth request to http://api.eventful.com/rest/oauth/validate This call will accept the Oauth paramaters as any of query string parameters, POSTed Data or as HTTP Authorization header. It will return whether or not the Oauth signature is correct, what Oauth parameters it was able to decode and what other parameters you passed in that it used in calcuating the the signature. You need to pass in a new parameter called valid_url with the url that you would have requested. Below is sample output of a call and what you can expect to see coming back

I don't see popularity in the search results.

I see refence to popularity but I don't see it in the search results, where is it?

To see the popularity of an event in the search results you need to add in popularity to your include parameter in your search request. For example &include=popularity. See the search documentation and look at the include parameter here.

Page_size and or Page_number doesn't seem to work

I tried setting page_size to 1000 so why do I only get back 250 records?

To make sure our api cluster is not overloaded we limit the page_size to a max of 250 for all requests. We also limit the page_number so you can not go past 1250 records. For example if your page size is 250 and you request page number 10 we will limit that and give you page number 4 (records 1000 through 1250).
If you really need to get past record 1250 you can get an xml feed of the data which will have all the records at once.

What does popularity mean

What does a popularity of 0004 mean?

Popularity is a fuzzy number that gives an indication of an event popularity but is not an exact number. If you see a popularity of 0023 and 0024 is the 0024 more popular than the 0023? It may or may not but in general as the number goes up the more popular the event is. The number works best when sorting. If you sort by descending popularity the biggest most popular, recognizable events will appear first, and the least popular will be last.

Image Sizes

I want to get an image bigger than a thumbnail in the results, how do I do that?

To do a search with different image_sizes you can pass in a comma separated list of sizes in the query string as paramater image_sizes. For example:
http://api.eventful.com/rest/events/search?...&date=ThisWeek&location=rennes&image_sizes=block100,large,dropshadow250