Adding the Eventful API to your Website

Eventful is a website that allows users to find and share events. It is a web service that allows it's users to add information about events, venues, and performers. Users can find local events as well as around the world. It you're looking for something to do, chances are Eventful will be able to find local events happening around you every day!

In this article we will explore how easy it is to add the Eventful API to a website using WebMatrix.

Create a website with WebMatrix

After WebMatrix is finished installing, open it. If you need help downloading and installing WebMatrix, it may be a good idea to read Getting Started with WebMatrix. The article provides step by step instructions on installing WebMatrix.

Open WebMatrix. Click "Site from Template" on the WebMatrix welcome screen.

For this example we will use is an Empty Site template. This template is a full-featured HTML5 site. Click Empty site and hit ok.

Clicking ok will take you to your WebMatrix workspace. This contains information about your local host as well a provides resources on developing your site.

You’ll notice that WebMatrix allows you to move between different workspaces by selecting the buttons on the left hand side. At present the Site button is selected which gives you details on your web site, such as the URL of the site, and other tools that you can use such as monitoring your site requests. You can look into this workspaces as you work but for this article, we will be working with our Files workspace. To get to your Files workspace, click the "Files" tab on the lower left hand of WebMatrix.

Once in your Files workspace you can see all your files. Since we chose the Empty Site template, we do not have any files. Let's create a new file for our website. Click the new button on the menu ribbon.

Here you can see all the different types of files you can make. Choose the .cshtml file, give it a name and hit ok.

We now have an empty, HTML5 valid website waiting for us to add code. You may be wondering why we created a .cshtml file instead of a traditional .html file. A .cshtml file is a new, special file type for WebMatrix. This type of file can contain the usual contents of a webpage including HTML and JavaScript code but, what sets it apart from a regular .html file is that it can also contain code for programming webpages. .cshtml files let you embed ASP.NET code into your HTML page using the new Razor syntax (which is most commonly denoted using @ - similar to PHP's $).

Razor code can go anywhere on your webpage. Blocks of code (written between @{ }), single line statements, and even single variables can be put anywhere, just make sure you have the correct syntax! If you want a more in-depth introduction to WebMatrix, you can find numerous resources on the subject including the asp.net website.

We'll look at how to add a Eventful RESTful request to our webpage.

Get your Eventful API Key

Visit the Eventful API website. It lays out some simple steps to get you started using the Eventful API.

The first thing we need to do is request an API key. Before we can do that though you must log in to your Eventful account or create a new account.

Click on the "application key" link. You will then be notified that you must create a new account or sign in (if you are not already signed in).

Click the "sign in" link if you already have an account.

Or, click the "register a new account" link if you need to sign up for an Eventful account. You will be asked to provide your name, email address, user name, and password.

Once your signed in, you will see your API keys listed on the page. Since we haven't requested a key yet, there are none listed here.

Click the "request an application key" link to get your key. You will be asked to fill in a simple form.

Once you've submitted the form, you will get a confirmation email with your API key. Also, your application key will now be listed on the Eventful website.

Now we can get started using the Eventful API.

Add the Eventful API to your website

Eventful provides a great API documentation. Here you can find information about all the different API methods you can use to make web requests.

This article will look at how to apply the Eventful API in two different ways. First, we will use the event search method. Second, we will use the event rss feed. Let's look at the event search first.

Information about the Eventful Search api can be found here. The Eventful Search API is rich - there are numerous parameters that can be supplied in order to retrieve the information that you want. Eventful even provides a Search Tutorial found here.

For this example, let's allow the user to enter their search terms that we will supply to the Eventful API. To do this, we must have a form on our webpage. Let's add that form now. In the .cshtml file you created earlier, add between <body> and </body>:

<form action="" method="post">
    <fieldset style="width: 250px">
        <legend>Please enter your search terms</legend>
        <div>
            <label for="whereLocation">Where:</label>
            <input type="text" name="location" value="" />
        </div>
        <div>
            <label for="whenTime">When:</label>
            <input type="text" name="when" value="" />                
        </div>
        <div>
            <label>&nbsp;</label>
            <input type="submit" value="Submit" class="submit" />
        </div>
    </fieldset>
</form>

You can run your page now to see your form. Click "run" on the menu ribbon. Your page will open in your default browser.

If you click the form's submit button nothing happens. That's because we haven't written code to do anything when we post our form. Let's add that code now.

To use the information the user submits in our form we must post the form. With forms, there are 2 different ways to get info from a form: get and post. If you look at our form code we added earlier, you can see that we've already specified that the action of our form will be post.

WebMatrix provides a isPost property that see if our web request is either a get or post. We can use this to get the form's information once it is submitted. Let's add that code now to our webpage. At the very top of the page, add:

@{      
    if (IsPost) {
        string location = Request["location"];
        string when = Request["when"];
        if (@location != "" && @when != "") {
            string uri = "http://eventful.com/events?q=music&l=" + @location + "&t=" + @when;
            Response.Redirect(uri);
        } 
    }
}

Our code first checks if our form has been submitted. If it has, we retrieve the information that was submited in our form and save it into variables. We then check to see if the user has submitted the form with empty text boxes. If they haven't, we then create our uri that we will use to create our web request. Once the uri is created, we redirect our page to the Eventful page that has the results to our search string.

Let's try our code out now. Run your code and enter a location and date search.

Once you submit this information you will be taken to the Eventful page with your search results.

Your full code should be similar to this:

@{      
    string error = String.Empty;
    if (IsPost) {
        string location = Request["location"];
        string when = Request["when"];
        if (@location != "" && @when != "") {
            string uri = "http://eventful.com/events?q=music&l=" + @location + "&t=" + @when;
            Response.Redirect(uri);
        } else {
            error = "Please enter your search terms";
        }
    }
}
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <title>Eventful API</title>
        <style type="text/css">
            div { padding: 10px;}
        </style>
    </head>
    <body>
        <h1 align="center">Eventful API Example</h1>
        <div style="float:left; width: 500px; margin-left: 15%; margin-right: 50px;">
            <p>You can add an eventful search to your site. 
This example would redirect your user to the eventful page with their search results.</p>
        </div>
        <form action="" method="post">
            <fieldset style="width: 250px">
                <legend>Please enter your search terms</legend>
                <div>
                    <label for="whereLocation">Where:</label>
                    <input type="text" name="location" value="" />
                </div>
                <div>
                    <label for="whenTime">When:</label>
                    <input type="text" name="when" value="" />                
                </div>
                <div>
                    <label>&nbsp;</label>
                    <input type="submit" value="Submit" class="submit" />
                </div>
                <div>
                    <p style="color:red;">@error</p>
                </div>
            </fieldset>
        </form>
    </body>
</html>

You may notice that a little bit of code has been added. This code creates an error variable. If the user tries to submit an empty form, they will receive an error at the bottom of the code. If you run this code and try to submit an empty code, your page would look similar to this:

Now, let's add an example of the Eventful API that does not redirect users off of your page.

Add another example of the Eventful API

Firstly, create a new .cshtml file by clicking on the "new" button on the menu ribbon.

For this example we will be using the events/rss method. More information about this method can be found here. This method returns the event search results in an RSS format. This uri is a bit different than the one we created before because this requires us to add our api key.

The Eventful API uses the RESTful format. This means that your webpage will make a request and you will receive a response with the information you requested. You can then do something with the requested information on your webpage. Because our response will be in XML (because we are using the RSS format), we can use the XMLTextReader class to parse our web response. To do that, we must define some directives. This must be done first thing on the page. At the very top of your .cshtml file, add:

@using System.Xml;
@using System.IO;
@using System.Text;

One of the nice things about the API documentation is that it provides the output parameters and an example of the response. This is helpful to look at before we create our web request so we know what information we want to retrieve from our response.

For this example we want the title, url and publish date of each event in our response. This means that we need variables for each of these. Add between @{ and } :

    string title = String.Empty;
    string urlLink = String.Empty;
    string pubDate = String.Empty;

Now we're ready to add our web request. Firstly, we need to create our request uri. Anywhere in your .cshtml (if must be after the code we added earlier) add your method call:

    string uri = 
"http://api.eventful.com/rest/events/rss?app_key={your-api-key}&keywords=concerts&location=seattle&sort_order=date";

Now we have constructed our uri. Let's add our web request and response. Like noted earlier, we can use the XMLTextReader to parse our response. Let's create that object now also. Add below our recently added code:

HttpWebRequest request = (HttpWebRequest)WebRequest.Create(uri);     
WebResponse response = request.GetResponse();
Stream strm = response.GetResponseStream();
XmlTextReader reader = new XmlTextReader(strm); 

Here we create our web request with our uri, get our web response and save it into a stream. We then create our XMLTextReader that we will use to parse through our response stream.

Let's add our code in the body of our webpage. Between <body> and </body>, add:

 @{
     int itemDepth = 0;

    while (reader.Read()){
        if (reader.Name == "item") {
            itemDepth = reader.Depth;
            reader.Read();
             while(reader.Depth != itemDepth) {  
                if(reader.Name == "title") {
                    title = reader.ReadString();
                } else if(reader.Name == "link") {
                    urlLink = reader.ReadString();
                } else if (reader.Name == "pubDate") {
                    pubDate = reader.ReadString();  
                } 
                reader.Read();        
            }
           <p><a href="@urlLink">@title</a><br />@pubDate</p>
        }
    }
    response.Close();
} 

Our code reads through our response until it gets to the item element. We then get the title, url and publish date of each event item. Once we've retrieved this information for an item, we then print it out to our webpage. We continue to do this until we reach the end of our response.

Let's run our code to see how our webpage looks. Click the run button on the menu ribbon.

Our whole code should be similar to this:

@using System.Xml;
@using System.IO;
@using System.Text;
@{
    string title = String.Empty;
    string urlLink = String.Empty;
    string pubDate = String.Empty;
    string uri = 
"http://api.eventful.com/rest/events/rss?app_key={your-api-key}&keywords=concerts&location=seattle&sort_order=date";
    HttpWebRequest request = (HttpWebRequest)WebRequest.Create(uri);     
    WebResponse response = request.GetResponse();
    Stream strm = response.GetResponseStream();
    XmlTextReader reader = new XmlTextReader(strm); 
}
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <title></title>
    </head>
    <body style="color: Gray">
        <h1 align="center">Eventful Events Near You</h1>
        <div style="width:600px; margin-left: 25%; border: 1px solid black; padding:10px">
 @{
     int itemDepth = 0;

    while (reader.Read()){
        if (reader.Name == "item") {
            itemDepth = reader.Depth;
            reader.Read();
             while(reader.Depth != itemDepth) {  
                if(reader.Name == "title") {
                    title = reader.ReadString();
                } else if(reader.Name == "link") {
                    urlLink = reader.ReadString();
                } else if (reader.Name == "pubDate") {
                    pubDate = reader.ReadString();  
                } 
                reader.Read();        
            }
           <p><a href="@urlLink">@title</a><br />@pubDate</p>
        }
    }
    response.Close();
} 
        </div>
    </body>
</html>

Now we have the events for Seattle listed on our page. If you wanted to get search results for something else, you can simply change the parameters in your uri string.

Those were just 2 examples of using the Eventful API. There are many more methods and possibilities for you to explore and use on your webpage.

Additional Resources

Download WebMatrix http://www.microsoft.com/web/webmatrix/

Learn how to Download and Install WebMatrix http://www.microsoft.com/web/post/web-development-101-part-1-getting-started-with-webmatrix

Learn more http://www.microsoft.com/web/post/Web-Development-101-using-WebMatrix

Create a website with a WebMatrix site template http://www.microsoft.com/web/post/create-a-website-from-a-webmatrix-site-template

Publish your website http://www.microsoft.com/web/post/how-to-publish-a-web-application-using-webmatrix

Learn to download, edit and republish your website http://www.microsoft.com/web/post/download-edit-and-republish-your-website-with-webmatrix

You can discuss this article using the adjacent Facebook talkback.

For technical questions please visit our discussion forums, where we have a vibrant community of developers like you, as well as Microsoft engineers who are ready to answer your questions!