The SEER API is a RESTful Web service that supports various SEER Program data sets and algorithms. This service is available to developers who wish to incorporate SEER resources into their own systems. These resources include databases and tools developed to enhance registry operations and quality improvement. The SEER API is designed for integration into registry computer systems and is not designed to be accessed by end-users.
The goal of SEER API is to provide a centralized repository of SEER Program tools that is available to all programming environments and operating systems. The API is based on REST principles, therefore, it is very easy to write and test applications. You can use your browser to access URLs and to test APIs. Any programming language that can read HTTP data from a URL can use web services. Results are returned in JSON format which can be easily parsed and interpreted. See the Usage page for language-specific examples.
The SEER API is currently powering a variety of SEER web tools, including:
The Surveillance, Epidemiology and End Results (SEER) Program is a premier source for cancer statistics in the United States. The SEER Program collects information on incidence, prevalence and survival from specific geographic areas representing 28 percent of the US population and reports on all these data plus cancer mortality data for the entire country.
The SEER API was designed in a RESTful way, so that your consumption of it is simple and straightforward.
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:
If you're looking for more information about RESTful web services, the O'Reilly RESTful Web Services book is a great place to start.
Using SEER API requires only a few simple steps:
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 Usage page.
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.
The SEER API is served over HTTPS. To ensure data privacy unencrypted HTTP 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/cstage/020550
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/cstage/020550?api_key=YOURAPIKEY
If there is a problem properly including your key in a request you will receive a 401 status code.
All APIs return JSON responses. It is not necessary to specify the response type for requests.
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.
|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.|
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:
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:
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.