The SEER API was designed in a RESTful way, so that your consumption of it is simple and straightforward.

From Wikipedia:

A RESTful web service (also called a RESTful web API) is a simple web service implemented using HTTP and the principles of REST. It is a collection of resources, with four defined aspects:

  • the base URI for the web service, such as http://example.com/resources/
  • the Internet media type of the data supported by the web service. This is often JSON, XML or YAML but can be any other valid Internet media type.
  • the set of operations supported by the web service using HTTP methods (e.g., GET, PUT, POST, or DELETE).
  • The API must be hypertext driven.

If you're looking for more information about RESTful web services, the O'Reilly RESTful Web Services book is a great place to start.

Getting Started

Using SEER API requires only a few simple steps:

  1. Create a free account from the Account Creation page
  2. Locate your API key on the Account page
  3. Build requests
  4. Receive your results

Individual APIs can be called from any modern programming language that can make standard HTTPS calls and process the results. For specific code examples, see the Example section below.

Creating an Account

SEER API user accounts are required to use the service. Accounts are free and can be requested using the Account Creation page. Each SEER API account is assigned an API key which is used to identify and authenticate a user. This key acts as a password to your data, so be sure to keep it private.

Building requests

The SEER API is served over HTTPS. To ensure data privacy, unencrypted HTTP communication is not supported. Every API resource is documented on the API page.

The easiest way to test APIs is to log into the SEER API website. While you are logged in, all requests you make in the browser will be automatically authenticated using your API key. If you wish to use SEER API in your own application then the API key must be attached to each request. The following examples are implemented using a command-line tool called cURL. It is a convenient way to test both the headers that are returned as well as the data.

  • Passed in using the X-SEERAPI-Key HTTP header. This is the preferred method.

    curl -H "X-SEERAPI-Key: YOURAPIKEY" https://api.seer.cancer.gov/rest/staging/cs/02.05.50/schemas
  • Passed in as an "api_key" parameter. This is a less secure way of passing the API key since it includes it in the URL. This should only be used for testing purposes.

    curl https://api.seer.cancer.gov/rest/staging/cs/02.05.50/schemas?api_key=YOURAPIKEY

If there is a problem properly including your key in a request you will receive a 401 status code.

Response type

All APIs return JSON responses. It is not necessary to specify the response type for requests.

HTTP Status Codes

All APIs return a status code indicating success or failure. Codes are returned using standard HTTP error code syntax. It is important to check the status code of every API call.

Code Description
200 Success (upon a successful GET, PUT, or DELETE request)
201 Created (upon a successful POST request)
400 Bad Request. Request wasn't formatted correctly or problem processing request input.
401 Unauthorized access (incorrect or missing authentication credentials)
403 Forbidden. This usually indicates the request was denied due to rate limiting.
404 Not Found. There is no method that serves the request path/resource.
405 Method Not Allowed (e.g., trying to POST to a URL that responds only to GET)
406 Not Acceptable (server can't satisfy the Accept header specified by the client)
409 Conflict. This usually indicates a stale version of an entity could not be updated.
500 Application Error.

Errors (non 200 codes) all return an object which includes the HTTP status code as well as a specific error message. For example, this is an error from an improperly formed URL request:

{
    "timestamp": "2017-07-10T13:00:05Z",
    "status": 404,
    "error": "Not Found",
    "message": "NDC code '0002-327' does not exist.",
    "path": "/rest/ndc/code/0002-327"
}

Rate Limiting

All API calls are subject to rate limiting. The current rate limit is 5000 API calls per hour. This limit should be high enough for most applications and we reserve the right to modify this limit in the future. Exceeding the rate limit will result in all resources returning a status code of 403 (Forbidden). Two HTTP response headers are included in every call:

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

If your application needs to exceed this limit, contact us. We may be able to help you better utilize the available API URLs or up your limits if necessary.

Examples

One of the strengths of REST-style web services is that they are both platform and language agnostic. As long as a programming language can make standard HTTPS calls and parse the results then they have all they need to access the web service.

As an example, we are going to query the disease search API for Hematopoietic cases with the term [Burkitt] and output only the identifiers and names in the results. The result should look like this:

51f6cf57e3e27c3994bd5324 - Burkitt lymphoma
51f6cf59e3e27c3994bd544a - Burkitt cell leukemia
51f6cf57e3e27c3994bd531e - Diffuse large B-cell lymphoma (DLBCL)
51f6cf57e3e27c3994bd5336 - Non-Hodgkin lymphoma, NOS

Each of the examples provided produce this same output.

Java

The best way to access SEER*API using Java is with the seerapi-client-java library. It is designed to make using the API as easy as possible. For more detailed information on the seerapi-client-java library including how to use it in your project, see https://github.com/imsweb/seerapi-client-java. Here is a sample using the library.

public class JavaExample {
    public static void main(String[] args) throws Exception {
        SeerApi api = new SeerApi.Builder().connect();
        DiseaseSearchResults results = api.disease().search("latest", "Burkitt").execute().body();

        results.getResults().forEach(d -> System.out.println(d.getId() + " - " + d.getName()));
    }
}

If you prefer to manually connect to the API, there are many libraries available in Java which makes REST API calls simple. This example uses the Apache HttpClient and Jackson libraries.

public class JavaExample {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClientBuilder.create().build();
        GetMethod get = new GetMethod("https://api.seer.cancer.gov/rest/disease/latest?type=HEMATO&q=Burkitt");
        get.addRequestHeader("X-SEERAPI-Key", "YOURAPIKEY");

        client.executeMethod(get);

        ObjectMapper mapper = new ObjectMapper();

        JsonNode results = mapper.readValue(get.getResponseBodyAsStream(), JsonNode.class);
        for (JsonNode result : results.get("results"))
            System.out.println(result.get("id").asText() + " - " + result.get("name").asText());
    }
}

Javascript

The example below uses the JQuery library.

<script type="text/javascript">
$.getJSON('rest/disease/latest?type=HEMATO&q=Burkitt&api_key=YOURAPIKEY&callback=?', function(data) {
    var output = '';
    $.each(data.results, function(key, val) {
        output += val.id + ' - ' + val.name + '\n';
    });

    alert(output);
});
</script>

Groovy

The example below uses a package called groovy-wslite which it downloads automatically if it is not locally available.

@Grab(group = 'com.github.groovy-wslite', module = 'groovy-wslite', version = '0.8.0')
import wslite.rest.*

def client = new RESTClient("https://api.seer.cancer.gov/rest/")
def response = client.get(headers: ['X-SEERAPI-Key': 'YOURAPIKEY'],
        path: '/disease/latest',
        query: [type: 'HEMATO', q: 'Burkitt'])

response.json.results.each {
    println it.id + " - " + it.name
}

C#

using System;
using System;
using System.Collections.Generic;
using System.Collections;
using System.IO;
using System.Net;
using System.Web.Script.Serialization;

namespace SeerUtilsCSharpExample {
    class Example {
        static void Main(string[] args) {
            // request json
            WebClient client = new WebClient();
            client.Headers.Add("X-SEERAPI-Key", "YOURAPIKEY");
            StreamReader streamReader = new StreamReader(client.OpenRead("https://api.seer.cancer.gov/rest/disease/latest?type=HEMATO&q=Burkitt"));
            if (streamReader == null)
                throw new Exception("OpenRead failed.");

            // create json reader
            JavaScriptSerializer deserializer = new JavaScriptSerializer();
            Dictionary<string, object> deserializedDictionary = deserializer.Deserialize<Dictionary<string, object>>(streamReader.ReadToEnd());

            // read and print output
            foreach (Dictionary<string, object> disease in ((ArrayList)deserializedDictionary["results"]))
                Console.WriteLine(disease["id"] + " - " + disease["name"].ToString());
        }
    }
}

Python

import urllib2
import json

request = urllib2.Request("https://api.seer.cancer.gov/rest/disease/latest?type=HEMATO&q=Burkitt")
request.add_header("X-SEERAPI-Key", "YOURAPIKEY")

response = urllib2.urlopen(request)

data = json.loads(response.read())
for disease in data['results']:
    print disease['id'] + " - " + disease['name']

Ruby

require 'net/https'
require 'json'

http = Net::HTTP.new('api.seer.cancer.gov', 443)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
response = http.get("/rest/disease/latest?type=HEMATO&q=Burkitt", "X-SEERAPI-Key" => "YOURAPIKEY")

result = JSON.parse(response.body)
result['results'].each do |disease|
   puts disease['id'] + " - " + disease['name']
end

Perl

use LWP::UserAgent;
use JSON;

$ua = new LWP::UserAgent;
$req = new HTTP::Request 'GET' => 'https://api.seer.cancer.gov/rest/disease/latest?type=HEMATO&q=Burkitt';
$req->header('X-SEERAPI-Key' => 'YOURAPIKEY');

# send request
$res = $ua->request($req);

# check the outcome
if ($res->is_success) {
    $json = from_json($res->content);
    for $disease ( @{$json->{'results'} } ) {
        print $disease->{'id'} . " - " . $disease->{'name'} . "\n";
    }
}
else {
    print "Error: " . $res->status_line . "\n";
}