Cancer Staging API

Related Pages

CDC has created software in the form of a dynamic link library (DLL) to help cancer registries collect data on stage of disease for cancers according to the TNM system of the American Joint Committee on Cancer (AJCC). Content from AJCC’s Cancer Staging Manual, 7th and 8th editions, has been licensed for use in the application programming interface (API) by NPCR registries. The TNM 8th edition staging library is intended to support the AJCC 8th edition standard, and is applicable for diagnosis years 2019 and later. It exists independently of the TNM 7th edition staging library.

Versions without the licensed content can be downloaded from this site. For access to the licensed versions, contact cancerinformatics@cdc.gov.

Features

The DLL has several primary functions—

  • Identifies cancer schemas, i.e., chapter in the manual or disease, based on the diagnosis coded in ICD-O-3.
  • Helps cancer data abstractors by providing cancer site-specific picklists of valid codes for the T, N, M, and stage groups, at the different points in the course of disease.
  • The 7th edition version helps central registries perform quality control and data consolidation by providing an algorithm to calculate the correct stage group from coded T, N, and M values.
  • The 8th edition version associates relevant cancer site-specific picklists of valid codes for site-specific data items (SSDIs), EOD, and Summary Stage 2018 tables with the selected schema.

The DLLs can be incorporated in cancer registry software programs to support standardized collection of TNM and other staging data.

Technical Information, Download, and Installation

8th Edition DLL

The TNM 8th edition staging library has been implemented in both C++ and C# as 32-bit and 64-bit Windows DLLs.

  • C#:
    • The C# library requires the .NET Framework version 4.5 or higher to be installed.
    • The C# library calls the C++ library to do its work. If the C# library is used, both libraries must be present in the same folder.
  • C++:
    • The C++ library comes with an interop wrapper for users who want to call the C++ library from .NET without using the C# library.

Both DLLs are included in the release package, along with API documentation, code files and wrappers, and sample programs.

Underlying contents are incorporated from AJCC’s API and from SEER*RSA. Each release of the TNM8 staging library has an assigned version (one for C++, one for C#), plus the version of AJCC and SEER RSA that was used in the build.

As of September 17, 2019 (third release):

  • Current TNM8 version: 8.4.8.72 (C++), 8.1.5.16 (C#)
  • Current AJCC content: 01.04.02
  • Current SEER RSA content: 1.7

Link to unlicensed version of TNM 8th edition staging library

Unlicensed_TNM8_Release_09_17_19.zip ZIP (ZIP file, 5 MB, October 9, 2019)

Known issues

September 17, 2019

  • Paget disease of breast—there have been extensive discussions among standard setters about coding of behavior and stage for mammary Paget disease. AJCC allows staging these cases as in situ. Solid tumor rules distributed by SEER state to code behavior 3 for these. In CDC’s staging API, a breast case (C50_) with histology 8540/2 is assigned AJCC ID XX (not stageable with TNM). The edit _SYS AJCC ID, Primary Site, Histology, Behavior (NAACCR) expects an AJCC ID of XX for breast cases with 8540/2. According to AJCC, the AJCC ID should be 48.1, DCIS. (SEER*RSA assigns AJCC ID 48.1.)

    Since correcting CDC’s staging API and the edits metafile would require new releases with added delays, it was decided to not make the changes until the release of components for 2021. At that time, existing cases of Paget disease can be corrected according to a conversion algorithm.
  • There is some uncertainty as to the appropriate value of AJCC ID for cases described in chapter 45 of AJCC’s manual, “Soft Tissue Sarcoma—Unusual Histologies and Sites.” AJCC describes the chapter as an “informational chapter, no staging system.” SEER*RSA assigns a value of 45, while our API assigns XX. This is not a serious problem because TNM is not applicable in either case. Edits have been loosened to allow both 45 and XX.
  • Indenting/white space in descriptions—For some tables with multiple lines in descriptions, white space appears as indenting for subsequent rows caused by line breaks in the original content provided to CDC. The issue will be corrected in a future version.

7th Edition DLL

The library exposes an API. The library is written in C# and .NET. A basic understanding of C# is required to use the API. A Microsoft® Windows environment with .NET Framework version 4.5 or higher is required.

Note June 2, 2017: A revised API was released on June 2, 2017. The changes from the February 2017 release are—

  • Additional clinical N values added to TNM Path N [NAACCR item 890] for the following schemas—
    • All GIST schemas
    • Corpus Uteri Carcinomas
    • Bone
    • Melanoma of Skin
    • Soft Tissue Sarcoma
  • Prostate—Derivation algorithm for NPCR Derived Path Stg Grp [NAACCR item number 3655] was revised to use the higher of the Gleason scores coded in SSF8 and SSF10.
  • Derivation algorithm for NPCR Derived Clin Stg Grp [NAACCR Item Number 3650] modified to derive stage in situ for Tis N0 M0 regardless of grade code for the following schemas—
    • Esophagus Squamous Cell Carcinoma
    • Esophagus Adenocarcinoma
    • Esophagogastric Junction Squamous Cell Carcinoma
    • Esophagogastric Junction Adenocarcinoma

Note February 20, 2017: A revised API was released on February 20, 2017. The changes from the October 2016 release affect the derived clinical and pathologic stage groups for the following schemas—

  • Breast
  • Lung
  • Lymphomas, Primary Cutaneous
  • Malignant Melanoma of Ciliary Body and Choroid
  • Malignant Melanoma of the Iris

Note October 17, 2016: A revised API was released on October 17, 2016. The changes from the initial release include—

  • Removal of codes ‘c0’ from the pathologic N tables for schemas for which AJCC does not provide an in situ category.
  • Added validation of directly entered stage groups for lymphomas before calculation of derived stage groups.
  • Enhanced API documentation with an index and additional hyperlinks.

Download the version without the licensed content—

The contents of the zip file include—

  • The TNM staging library.
  • The API documentation (.chm file).
  • A sample code file, to be used in conjunction with the API documentation.

TNM 7th Edition Staging Batch Calculation Tool

The TNM staging batch calculation tool is a standalone application that accepts a flat file of records in NAACCR v16 format, derives values for the standard items NPCR Derived Clin Stg Grp (item 3650) and NPCR Derived Path Stg Grp (item 3655), and writes the results to an output file and log file. It can be used by any registry whether or not they hold a license for AJCC copyrighted contents. The batch calculation tool incorporates the TNM staging API version released June 2, 2017. The download file contains notes and instructions for use.

Initial release: June 30, 2017

Download: TNM7_BatchApplication.zip ZIP [ZIP-548KB]

Page last reviewed: October 16, 2019
Content source: Division of Cancer Prevention and Control, Centers for Disease Control and Prevention