Hack the News with the New York Times API

The New York Times, one of the most well known and read newspapers, offers numerous APIs. These APIs allow you to display content from the NY Times on your webpage. You can use these APIs to essentially "hack" the news!

Create a website with WebMatrix

In this article, we will be using WebMatrix. WebMatrix is a free tool that allows you to create, customize, and publish webpages. It gives a number of different ways that you can create websites. One of the features is providing existing open sources applications such as WordPress, Joomla, DotNetNuke or Umbraco. WebMatrix can be downloaded for free at microsoft.com/Web/WebMatrix .

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

Let's get started creating a new webpage with WebMatrix.

After WebMatrix is finished installing, open it. 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 Starter 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 choose a Starter Site, we have numerous files that make up our website.

Let's see what our site looks like. With Default.cshtml selected, click the run button on the menu ribbon.

Your page will open in your default web browser. You have a simple starter website where you can add functionality and other features to customize it.

We can now get started "hacking" the news onto our website.

Get a NY Times API Key

The NY Times Developer website contains all the information required to get started using their APIs.

Found on the developer page is instructions on how to get started using their APIs.

You may notice that the first thing we need to do is request an API key. This requires us to have a NY Times account.

Sign Up for an account. You will be asked to enter an email address and a password.

When you are done entering your account information, click the button at the bottom of the page.

When you've submitted your account information you will receive a confirmation email. Before you can log in with your new account, you must activate your account through the email.

Clicking on the link in your email will activate your account. You will have the option to choose to receive free emails. You can either select some or simply continue on.

Once you've finished creating an account and have logged in, you can now request your API key. Go back to the developer website to request your key. Click the "request a key" link on this page.

You will need to register your application. Give your application a name and choose which APIs you will want a key for. This article will show how to use the "Most Popular" API. However, since all the APIs function the same, you can choose whatever API you wish to use.

Once you've submitted your application information you will be directed to a page where your API keys are located. You will also receive a confirmation email with your API key.

Click the API link on the right or go here to see the information about the APIs.

Add the NY Times API to your website

The Most Popular API allows you to request links and metadata for blog posts and articles that are the most popular in reader's email, shared, and viewed on the NY Times website.

The NY Times APIs use 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.

This page contains a great deal of useful information. It provides information about the request's required and optional parameters, examples of responses, and examples of the responses from the requests.

A great thing that NY Times provides is a uri request generator. You simply put in the parameters that your wish to use and the generator creates the uri for you. All you have to do is add the API key you received. The generator can be found here.

Head back to WebMatrix. Open your Default.cshtml file. This is where we will add our API. You may notice that this page only contains some Razor code and a <p>. 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.

The Starter Site template we choose creates a web application that used a Site Layout. The Razor code at the top of the page applies the site layout to your page. It also defines the title on the page. Using a site layout for your web application creates a consistent look and feel for your page.

Let's add our API. Firstly, you can remove the <p> on the page (you don't have to but the <p> is unnecessary). The first thing we need to add is our uri. We'll save this in a variable. Add below the Razor code and before the closing }:

string uri = "http://api.nytimes.com/svc/mostpopular/v2/mostviewed/arts/7.xml?api-key={your-api-key}";

You can place any request uri in the value of the variable "uri". Also, make sure you replace {your-api-key} with the API key you were given. The request uri here requests the most popular articles that were most viewed in the arts section in the page 7 days. It also requests that the response be in xml format. The NY Times API also allows you to receive responses in JSON as well as PHP. For this article we will be working with XML response since c# has a nice class to read XML text.

Now that we have our request code, let's add the code that makes the request and receives the response. Directly below the code we just added, add:

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

This code creates the HTTP request, gets the server's response, and places the response in stream. It also create a new XMLTextReader object that we will use to read through our XML response.

Now that we have our response we need to read through it. Let's create a <div> on our page and put our results in it. Add:

<div id="topStories">
</div>

Let's now read through our response and add the information to our page. Firstly, we need to decide what information we want from our response. Examples of the XML document we will receive can be found when we generated our uri or on the Most Popular API page.

In this article we will want to retrieve the url of the article, the byline, the title and the abstract. We'll create variables for each of these bits of information and then loop through our XML and print of the information. Add this code between <div> </div>:

@{
        string url = String.Empty;
        string author = String.Empty;
        string title = String.Empty;
        string summary = String.Empty;
        int itemDepth = 0;

    while (reader.Read()){
        if (reader.Name == "result") {
            itemDepth = reader.Depth;
            reader.Read();
             while(reader.Depth != itemDepth) {  
                if(reader.Name == "url") {
                    url = reader.ReadString();
                } else if(reader.Name == "byline") {
                    author = reader.ReadString();
                } else if(reader.Name == "title") {
                    title = reader.ReadString();
                } else if (reader.Name == "abstract") {
                    summary = reader.ReadString();
                }
                reader.Read();        
            }
           <p><a href="@url">@title</a><br />@summary<br /><i>@author</i></p>
        }
    }
    response.Close();
} 

We use the XMLTextReader to loop through our document. Each time we reach an <result> node we read through setting all of our variables to the correct values. Once we get to the closing <result> node we print out our information on the page.

Let's run our page to see how our API works.

We now see our page but instead of the <p> that was there before, we now have the most viewed articles in the arts section from the past 7 days. Clicking on the article links will take us to NY Times website where we can read the full article.

Our whole code looks similar to this:

@using System.Xml;
@using System.IO;
@using System.Text;
@{   
    Layout = "~/_SiteLayout.cshtml";
    Page.Title = "The Most Viewed NY Times Stories";
    string uri = "http://api.nytimes.com/svc/mostpopular/v2/mostviewed/arts/7.xml?api-key={your-api-key}";
    HttpWebRequest request = (HttpWebRequest)WebRequest.Create(uri);     
    WebResponse response = request.GetResponse();
    Stream strm = response.GetResponseStream();
    XmlTextReader reader = new XmlTextReader(strm); 
}
    <div id="topStories" >
    @{
        string url = String.Empty;
        string author = String.Empty;
        string title = String.Empty;
        string summary = String.Empty;
        int itemDepth = 0;

    while (reader.Read()){
        if (reader.Name == "result") {
            itemDepth = reader.Depth;
            reader.Read();
             while(reader.Depth != itemDepth) {  
                if(reader.Name == "url") {
                    url = reader.ReadString();
                } else if(reader.Name == "byline") {
                    author = reader.ReadString();
                } else if(reader.Name == "title") {
                    title = reader.ReadString();
                } else if (reader.Name == "abstract") {
                    summary = reader.ReadString();
                }
                reader.Read();        
            }
           <p><a href="@url">@title</a><br />@summary<br /><i>@author</i></p>
        }
    }
    response.Close();
} 
   </div>

This was just 1 example of how you can use the NY Times API. To use some of the other APIs you simply have to change your uri request and the XML nodes that you wish to retrieve the information from.

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!