Intro

    Purpose

    Federal RePORTER APIs are designed to programmatically expose relevant scientific awards data from both NIH and non-NIH federal agencies for the consumption of project teams or external 3rd party applications to support reporting, data analysis, data integration or to satisfy other business needs as deemed pertinent.

    Audience

    Primary focus groups consist of developers, solution architects, and technical architects. Business users such as CIOs, program managers, project managers or other technology executives are another potential audience who might be interested in understanding the value of Federal RePORTER API for their projects before involving their technical teams.

    API Endpoints

    For the endpoints supported by the Federal RePORTER APIs, the interface below lists the parameters that can be used to retrieve the relevant data in JSON or XML format. You can enter a valid value for one or more parameters and click the "Try it Out" button. System will return:

    • Curl script for executing the API using a command line interface (CLI).
    • The Response Body showing the actual data.
    • Request URL, Request Headers, and Response Headers with relevant information.

    The Model (Example Value) section shows the output fields along with their data types in a format based on the Response Content Type selection.

    Constraints/Limitations

    • Federal RePORTER APIs do not support fuzzy, proximity, or range based searches.
    • The API service will be available except during a pre-scheduled maintenance window. Appropriate maintenance messages will be posted in advance on the API site.
    • In order, not to overload the Federal RePORTER API servers, it is recommended that users post no more than three URL requests per second and limit large jobs to either weekends or weekdays between 9:00 PM and 5:00 AM EST.
    • Failure to comply with this policy may require administrators to block your IP address from accessing the API service. For any questions regarding use of the Federal RePORTER API, please reach out to the support team at FederalRePORTERFeedback@mail.nih.gov.

    Data Input and Output

    Federal RePORTER APIs can consume different input parameters based on the type of endpoint.

    Search Endpoint

    Separator Purpose
    Colon (:) Separates the project property and the values.
    Comma (,) Delimiter to separate multiple values for a project property.
    Dollar ($) Separates the project property and values pairs, when search criteria have more than one project properties to search on.
    Semicolon (;) Delimiter only for Principle Investigator (PI) names.
    Parameter Description
    query
    accepts one or more of the project properties listed below    		 The query parameter (query=) lets the user search on one or more properties of a project (listed in the table below).

    The search criteria in the URL is of the format ‘query=ProjectProperty1:value1,value2(s)$ProjectProperty2:value1,value2…’
    offset Users can set the starting counter for the items (projects). By default, it starts at 1.

    Example: Out of a total of 100 items, if you want to retrieve items starting from #60, you must set the offset value to 60.
    limit Users can set this parameter to restrict the number of project records per request. Maximum allowed value is 50, which is also the default if no value is specified.
    sortBy Below fields are currently available for sorting. Users can set sortBy parameter to sort the results. Sorting is allowed for one field at a time,
    • Fiscal Year: parameter fy
    • Organization Name: parameter OrgName
    • Project Cost: parameter totalCostAmount
    sortOrder Users can set this parameter to apply the sort order as ascending (asc) or descending (desc).
    Query Property How to Use
    projectNumber Complete Project Number or a partial one with wild card option.

    Examples:
    query=projectNumber:5R01NR014792-03 (Exact Match)
    query=projectNumber:*R01* (Wildcard, containing R01)
    query=projectNumber:USFS* (Wildcard, starting with USFS)
    query=projectNumber:*NR014792 (Wildcard, ending in NR014792)
    text One or more terms, each separated by a space, to retrieve projects that reference those terms. Following parameters give users additional control over text based search:
    • textFields: By default, the search happens across fields - project terms, project title and abstracts. Users can restrict the API to search against one or more of the above listed fields by supplying the field names as part of the input parameter.

      Example:
      query=text:cancer biology$textFields:title,abstract
      (Searches for projects where both the terms cancer and biology appear in Project Title and Abstract)

    • textOperator: For more than one term, by default an “AND” operation is performed.
      Users can specify the “OR” operator to pull up all the projects that contain one or more of the entered terms.

      Example:
      query=text:cancer biology$textFields:title,abstract$textOperator:OR
      (Searches for projects where the either of the terms cancer or biology appears in in Project Title and Abstract)
    fy One or more fiscal years, each separated by a comma, to retrieve projects that correspond to (or started in) one of the fiscal years entered.

    Example:
    query=fy:2014
    query=fy:2014,2015 (comma separated)
    agency One or more comma separated agency codes to retrieve all associated projects. For simplicity, this parameter can accept codes for a department of the U.S. government, federal agency or NIH Institute/Center. View complete list of valid agency codes.

    Example:
    query=agency:NIH
    query=agency:NIH,VA,FDA (comma separated)

    Note:
    • When a higher-level department or agency such as DOD, HHS or NIH is one of the values passed, then the API shall return projects associated with all lower level offices by default.
    piName One or more semi-colon separated project investigator (PI) names to retrieve all projects associated with any of the PI names passed.

    Example:
    query=piName:TRAPNELL, BRUCE (lastname, firstname)
    query= piName:KHAYAT, RAMI;NEMETH, ELIZABETA (multiple names separated by ‘;’)

    Notes:
    • Search API checks against both the primary PI and Other PIs associated with a project to find a match.
    • First name and last name should be separated by a comma but the order does not matter as the API will retrieve a project if the entered name matches either the first or the last name of a PI
    orgName Exact or Wildcard search.

    Examples:
    query=orgName:BOSTON UNIVERSITY (exact)
    query=orgName:VANDERBILT* (wildcard)
    Only one organization name can be passed at a time.
    orgState US States or Territories to which a project organization belongs to.

    One or more comma separated codes (two characters) for US States or US Territories to retrieve all associated projects. View complete list of valid US States/Territories codes.
    No wildcard search allowed.

    Examples:
    query=orgstate:MD
    query=orgstate:MD,NY,GU
    Combined with multiple fields (with fiscal year and agency name below)
    query=orgstate:CA$fy:2016$agency:NIFA

    Output for Search Endpoint

    Search based API returns a specific number of project records per page based on the values set for the parameters “offset” and “limit” along with the total project count.

    Get Project Endpoint

    Parameter Description
    smApplID It is an internal Federal RePORTER generated unique ID associated with each project. It is available as part of export on Federal RePORTER search results. Example, 739576.
    nihApplId It is a global identifier for a project across all NIH systems that handle research projects/grants data. Example, 8828294.
    projectNumber It is a unique number that is assigned to a project by the affiliated federal agency. Examples, 5R01MH092950-05, 1R01CA183929-01A1, USFS-0000779.

    Output for Get Project Endpoint

    Only one project record is retrieved with each API call.

    Fetch Projects by SM Appl Id(s) Endpoint

    Parameter Description
    FetchBySmApplids Users can enter one or more SM Appl Ids as a comma separated array of integers.

    Fetch Projects by Project Numbers(s) Endpoint

    Parameter Description
    FetchByProjectNumbers Users can enter one or more Project Numbers as a comma separated array of strings.

    Note: Only one type of parameter is allowed in a single API call. For example, users can not use SM Appl Ids and Project Numbers both in the same API call.

    Output for Fetch Based API

    Fetch based API returns a maximum of 50 project records at a time. Users must keep track of the SM Appl Ids or Project Numbers for which the data is already retrieved.

    Data Elements

    All three types of APIs (single project, fetch, and search) will return the set of data elements shown in the table below. This list is based on the current Export capability in Federal RePORTER.

    Category Data Elements
    Project Description Project Abstract
    Project Terms
    Project Title
    Project Details Department
    Agency
    IC
    SM Application ID
    Project Number
    Project Start Date
    Project End Date
    Personnel Contact PI/Project Leader
    Other PI/Project Leader
    Funded Organization Congressional District
    DUNS Number
    Latitude
    Longitude
    Organization Name
    Organization City
    Organization State
    Organization ZIP
    Organization Country
    Project Funding Budget Start Date
    Budget End Date
    CFDA Code
    Fiscal Year
    Total Cost