Intro

    Purpose

    NIH 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 NIH RePORTER API for their projects before involving their technical teams.

    What's New

    Project API- A new version (V2) of Project API has been released. Systems and users will have the option to utilize new payload criteria and retrieve additional data elements.
    Publication API - The RePORTER API is enhanced to include a new end point for publication search.

    Refer to additional materials and instructions on how to use the API - V2.0.

    New data elements added to Project V2 API :

    Data Element GroupData Elements
    Project Details
    • URL for RePORTER's project details page
    Funded Organization
    • Organization Department
    • Organization DUNS number
    • Organization UEI
    • FIPS
    • Organization ID (IPF)
    • Organization ZIP
    Project Funding
    • ARRA Indicator
    • Budget Start Date
    • Budget End Date
    • CFDA Code
    • Direct Costs
    • Indirect Costs
    • Funding Mechanism
    • Opportunity Number
    Study Section
    • SRG Code
    • SRG Flex
    • SRA
    • Designator Code
    • SRA Flex Code
    • Group Code
    • Study Section Name

    Data elements added to Publication Search API:

    Payload Criteria
    • pmids
    • appl_ids
    • core_project_nums
    Response Data Elements
    • Core Project Number
    • PMID
    • Latest Application ID

    API Endpoints

    For the endpoints supported by the NIH RePORTER APIs, the interface below lists the payload criteria that can be used to retrieve the relevant data in JSON format. You can enter a valid value for one or more criteria parameter 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

    • NIH RePORTER APIs do not support fuzzy, proximity, or range based searches except where specified.
    • 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.
    • To provide quality service for all users of NIH RePORTER web and API servers, it is recommended that users post no more than one URL request 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 NIH RePORTER API, please reach out to the support team at RePORT@mail.nih.gov.

    Data Input and Output

    NIH RePORTER APIs can consume different input parameters based on the type of operator.

    Search Parameter Operators
    SeparatorPurpose
    Colon (:)Separates the project property and the values. E.g. "sort_field":"project_start_date"
    Comma (,)Delimiter to separate multiple values for a project property. E.g. multiple opportunity numbers are specified as list: "opportunity_numbers":["RFA-DA-18-020","PAR-18-218","PAR-18-219"]
    Payload PropertyDescription
    payload
    accepts one or more of the project properties listed below    		The list operator (property: [] ) lets the user search on one or more properties of a project (listed in the table below).

    The search criteria in the Payload is of the format property=[Value1, Value2, Value3, ...]’
    include_fieldsUsers can specify the include fields to return only required fields/columns from the result.

    Example: The output result payload would have only ten fields/columns: "include_fields": [ "ApplId","SubprojectId","FiscalYear","OrgName","OrgCity", "OrgState","OrgStateName","DeptType", "ProjectNum","OrgCountry" ]
    exclude_fieldsUsers can specify the exclude fields to remove the fields/columns from the output result.

    Example: The following two fields won't appear in output result payload: "exclude_fields": [ "ProjectStartDate","ProjectEndDate" ]
    offsetUsers can set the starting counter for the items (projects). By default, it starts at 0. Offset doesn't support negative number.Maximum allowed value is 14,999. In addition, the requested Offset value shall not exceed total records count.

    Example: Out of a total of 100 items, if you want to retrieve items starting from #60, you must set the offset value to 59.
    limitUsers can set this parameter to restrict the number of project records per request. The default value is 50, if no value is specified. Maximum allowed value is 500.
    sort_fieldUsers can specify the sort field in the payload to sort the result by a specific field.
    sort_orderUsers can set this parameter to apply the sort order as ascending (asc) or descending (desc).
    search_idSearch Id is a unique id generated by the system. After the initial request with search criteria, the search results can be retrieved in subsequent requests by using the Search Id. This Search Id can also be used to request the same data from advanced search in the RePORTER web application. No additional payload criteria shall be used when using search_id.
    Example: {"search_id": "JbRgAtchAUKHOoW2X1vObQ"}
    urlA web URL with search ID is generated in the RePORTER API meta properties when the call includes criteria. The URL allows viewing the full API result set in the RePORTER.
    Payload CriteriaHow to Use
    use_relevanceIf sets true, it will bring the most closely matching records with the search criteria on top (those which have a high matching score).

    Examples:
    { "criteria": { "use_relevance": false } }
    { "criteria": { "use_relevance": true } }
    fiscal_yearsOne or more fiscal years, each separated by a comma in a square bracket, to retrieve projects that correspond to (or started in) one of the fiscal years entered.

    Examples:
    { "criteria": { "fiscal_years": [2018,2019] } }

    Note:
    • If searching for all fiscal years, use blank []. Example, { "criteria": { "fiscal_years": [] } }

    include_active_projectsReturn the result with active projects or ignore them. It takes true or false boolean value.

    Examples:
    { "criteria": { "include_active_projects": true } }
    pi_namesOne or more comma separated project investigator (PI) names in a square bracket to retrieve all projects associated with any of the PI names passed.

    Example:
    { "criteria": { "pi_names": [{"any_name": "gullo"},{"first_name": ""},{"any_name": "welch"},{"first_name": ""}] } }

    Note:
    • First Name, last name, and anyname are by default wildcard enabled so the user can search with partial name.

    po_namesOne or more comma separated project Officers (PO) names in a square bracket to retrieve all projects associated with any of the PO names passed.

    Example:
    { "criteria": { "po_names": [{"any_name": "gullo"},{"first_name": ""},{"any_name": "welch"},{"first_name": ""}] } }
    Note:
    • First Name, last name, and anyname are by default wildcard enabled so the user can search with partial name.

    org_namesOne or more comma separated organization names in a square bracket to retrieve all projects associated with any of the organization names passed.

    Example:
    { "criteria": { "org_names": [ "EMORY UNIVERSITY", "JOHNS HOPKINS UNIVERSITY", "NEW ECHOTA BIOTECHNOLOGY, INC.", "UNIV OF NORTH CAROLINA CHAPEL HILL" ] } }

    Note:
    • The organization's names implicitly searched with a wildcard. So,
      { "criteria": { "org_names": [ "JOHNS" ] } }
      will fetch all the "JOHNS HOPKINS UNIVERSITY" and other matching organization names records.

    org_names_exact_matchSince the org_names has by default wildcard functionality, the payload with org_names_exact_match parameter fetches records that exactly match with organization names.

    Example:
    { "criteria": { org_names_exact_match:["UNIV OF NORTH CAROLINA CHAPEL HILL"] } }
    pi_profile_idsOne or more comma separated project investigator profile Ids in a square bracket to retrieve all projects associated with any of the project investigator profile Ids passed.

    Example:
    { "criteria": { pi_profile_ids:[0,1] } }
    org_citiesOne or more comma separated organization cities in a square bracket to retrieve all projects associated with any of the organization cities passed.

    Example:
    { "criteria": { org_cities:["SAN JUAN","ANN ARBOR"] } }
    org_statesUS States or Territories to which a project organization belongs to. One or more comma separated organization states in a square bracket to retrieve all projects associated with any of the organization states passed. No wildcard search allowed.

    Example:
    { "criteria": { org_states:["MI","AL"] } }
    project_numsOne or more comma separated project numbers in a square bracket to retrieve all projects associated with any of the project numbers passed.

    Example:
    { "criteria": { project_nums:["5UG1HD078437-07","5R01DK102815-05"] } }

    Search Project Number by Wildcard: The project number can be searched by wildcard (* for zero or more occurrence)
    Example:
    { "criteria": { project_nums:["5UG1HD0784*"] } }
    project_num_splitPass one or more of the split project number values to retrieve projects matching all specified criteria.

    Example:
    { "criteria": { project_num_split: { appl_type_code: "1", activity_code: "F32", ic_code: "HL", serial_num: "149210", support_year: "01", full_support_year: "01A1", suffix_code: "a1" } } }
    spending_categoriesOne or more comma separated NIH Spending Category identifiers in a square bracket to retrieve all projects associated with any of the spending categories passed.

    Example:
    { "criteria": { spending_categories: { Values: [27,92], match_all: "false" } } }

    Note:
    • a match_all value of true will return projects found in all categories, while a value of false will return projects found in at least one of the categories.

    funding_mechanismOne or more comma separated Funding Mechanism codes in a square bracket to retrieve all projects associated with any of the funding mechanism passed.

    Example:
    { "criteria": { funding_mechanism: ["SB", "Other"] } }

    Note:
    • Users can specify "Other" to search for combined Funding Mechanisms "UK", "OT", and "CP"

    advanced_text_searchUsers can pass the full advanced text search parameters, which are operator, searchfield, and searchtext to filter the associated projects with advaced text search criteria.
    Values of logic operator can be "and", "or" or "advanced" respectively. Values of search field are "projecttitle", "terms", and "abstracttext", which can be comma separated.

    Example:
    { "criteria": { advanced_text_search: { operator: "and", search_field: "projecttitle,terms", "search_text": "brain disorder" } } }

    Note:
    • If searching text in all searching text in project titles, abstracts, and scientific terms, use "all" or "".
    • If the "And" logic is selected (the default), projects in which all of the search terms are found within the title, abstract, or scientific terms will be retrieved.
    • If the "Or" logic is used, projects that contain at least one of the terms entered will be retrieved. Use quotes(\") around the entered text to search for exact phrases.
    • The "Advanced" logic option provides additional capability to narrow selection criteria more precisely and evaluate complex entries such as chemical references.
    • Text search automatically disreagards certain common stop-words like a, an, and, are, as, at, be, of, on, or, into, is, it, etc.

    org_countriesOne or more comma separated organization countries in a square bracket to retrieve all projects associated with any of the organization countries passed.

    Example:
    { "criteria": { org_countries:["UNITED STATES"] } }
    appl_idsOne or more comma separated application IDs in a square bracket to retrieve all projects associated with any of the application IDs passed.

    Example:
    { "criteria": { appl_ids:[9754095,9754094,250963] } }
    agenciesOne or more comma separated agencies in a square bracket to retrieve all projects associated with any of the agencies passed.

    Example:
    { "criteria": { agencies:["NIGMS","AHRQ"] } }
    is_agency_adminPass the true or false value to filter the projects for admin agency status.

    Example:
    { "criteria": { "is_agency_admin": true } }
    is_agency_fundingPass the true or false value to check if agency is funding?

    Example:
    { "criteria": { "is_agency_funding": true } }
    activity_codesOne or more comma separated activity codes in a square bracket to retrieve all projects associated with any of the activity codes passed.

    Example:
    { "criteria": { activity_codes:["P20","R35"] } }
    award_typesOne or more comma separated award types in a square bracket to retrieve all projects associated with any of the award types passed.

    Example:
    { "criteria": { award_types:["5","8"] } }

    Note:
    • Use '4C' for competing type 4, '4N' for Noncompeting type 4.

    dept_typesOne or more comma separated dept types in a square bracket to retrieve all projects associated with any of the dept types passed.

    Example:
    { "criteria": { dept_types:["NONE","PEDIATRICS"] } }
    cong_distsOne or more comma separated cong dists in a square bracket to retrieve all projects associated with any of the cong dists passed.

    Example:
    { "criteria": { cong_dists:["PR-98","MI-12"] } }
    opportunity_numbersOne or more comma separated opportunity numbers in a square bracket to retrieve all projects associated with any of the opportunity numbers passed.

    Example:
    { "criteria": { "opportunity_numbers":[ "RFA-DA-18-020","PAR-18-218",] } }
    project_start_datePass the project start from and to date to filter the projects that starts within a specific duration

    Example:
    { "criteria": { "project_start_date": { "from_date": "2017-09-01", "to_date": "2019-09-01" } } }
    project_end_datePass the project end from and to date to filter the projects that end within a specific duration

    Example:
    { "criteria": { "project_end_date": { "from_date": "2017-09-01", "to_date": "2019-09-01" } } }
    organization_typeOne or more comma separated organization_type in a square bracket to retrieve all projects associated with any of the organization_type passed.

    Example:
    { "criteria": { organization_type:[ "SCHOOLS OF MEDICINE", "SCHOOLS OF ARTS AND SCIENCES",] } }
    award_notice_dateUsers can pass the from and to date of an award notice date to retrieve the associated projects within specified award notice dates. Projects with award notice date on or after the specified from-date will be retrieved when from_date is specified and to_date is unspecified. Projects with award notice date on or before the specified to_date will be retrieved when to_date is specified and from_date is unspecified.

    Example:
    By date range: { "criteria": { "award_notice_date":{ "from_date":"2021-02-16", "to_date":"2022-02-17" } } }

    On or before specified date: { "criteria":{ "award_notice_date":{ "from_date":"", "to_date":"2022-02-17" } } }

    On or after specified date: { "criteria":{ "award_notice_date":{ "from_date":"2021-02-16", "to_date":"" } } }
    award_amount_rangeUsers can specify the award amount range using min_amount and max_amount to retrieve projects awarded within specified amount range.

    Example:
    { "criteria": { "award_amount_range":{ "min_amount":0, "max_amount":50000000 } } }
    exclude_subprojectsPass the true or false value to exclude_subprojects to retrieve the associated projects with a selected value (true/false).

    Example:
    { "criteria": { "exclude_subprojects": true } }
    multi_pi_onlyPass the true or false value to multi-project inspectors (PI) to reterive the accociated projects with selected value (true/false).

    Example:
    { "criteria": { "multi_pi_only": false } }
    newly_added_projects_onlyPass the true or false value to newly added projects only to retrieve the associated projects with a selected value (true/false).

    Example:
    { "criteria": { "newly_added_projects_only": false } }
    sub_project_onlyPass the true or false value to sub-project only to retrieve the associated projects with a selected value (true/false).

    Example:
    { "criteria": { "sub_project_only": false } }
    covid_responseEnter one or more NIH COVID-19 Response project selectors, each separated by a comma in a square bracket, to retrieve projects awarded to study COVID-19 and related topics as funded under:
    All: All the COVID appropriations below
    Reg-CV: NIH Regular Appropriations Funding used for COVID-19 Research
    CV: Coronavirus Preparedness and Response Supplemental Appropriations Act, 2020
    C3: CARES Act (Coronavirus Aid, Relief, and Economic Security Act)
    C4: Paycheck Protection Program and Health Care Enhancement Act
    C5: Coronavirus Response and Relief Supplemental Appropriations Act, 2021
    C6: American Rescue Plan Act of 2021

    Example:
    { "criteria": { "covid_response": ["Reg-CV", "CV"] } }
    date_addedPass the project added from date and to date to filter the projects that are added to RePROTER within a specific duration. Projects added to database date on or after the specified from-date will be retrieved when from_date is specified and to_date is unspecified. Projects added to database date on or before the specified to_date will be retrieved when to_date is specified and from_date is unspecified. Dates are available from 1/1/2011.

    Example:
    By date range: { "criteria": { "date_added":{ "from_date":"2021-02-16", "to_date":"2022-02-17" } } }

    On or before specified date: { "criteria":{ "date_added":{ "from_date":"", "to_date":"2022-02-17" } } }

    On or after specified date: { "criteria":{ "date_added":{ "from_date":"2021-02-16", "to_date":"" } } }

    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.

    Data Elements

    The Search API will return the set of data elements shown in the table below.

    CategoryData Elements
    Project DetailsIC
    Support Year
    Application Type Code
    Activity Code
    Serial Number
    Suffix Code
    Project Number
    Core Project Number
    Project Start Date
    Project End Date
    Sub-Project ID
    Abstract
    Title
    Public Health Relevance
    RCDC Terms
    Study SectionSRG Code
    SRG Flex
    SRA Designator Code
    SRA Flex Code
    Group Code
    Study Section Name
    PersonnelPrincipal Investigators
    Program Officers
    Funded OrganizationCongressional District
    Organization Type
    Organization Name
    Organization City
    Organization State
    Organization ZIP
    Organization Country
    Organization Department
    Organization DUNS number
    Organization UEI
    Organization ID (IPF)
    FIPS
    Project FundingAward Notice Date
    Fiscal Year
    Opportunity Number
    Award Amount
    NIH COVID-19 Response
    ARRA Indicator
    CFDA Code
    Funding Mechanism
    Direct Costs
    Indirect Costs
    Budget Start Date
    Budget End Date

    Publication - Data Input and Output

    NIH RePORTER APIs can consume different input parameters based on the type of operator.

    Search Parameter Operators
    SeparatorPurpose
    Colon (:)Separates the publication property and the values. E.g. "sort_field":"coreproject"
    Comma (,)Delimiter to separate multiple values for a publication property. E.g. multiple core project numbers are specified as list: "core_project_nums":["T32GM062754","U01HL136297","F31HL149358"]
    Payload PropertyDescription
    payload
    accepts one or more of the publication properties listed below    		The list operator (property: [] ) lets the user search on one or more properties of a publication (listed in the table below).

    The search criteria in the Payload is of the format property=[Value1, Value2, Value3, ...]’
    offsetUsers can set the starting counter for the items (publications). By default, it starts at 0.
    Maximum allowed value is 9,999. In addition, the requested Offset value shall not exceed total records count.

    Example: Out of a total of 100 items, if you want to retrieve items starting from #60, you must set the offset value to 59.
    limitUsers can set this parameter to restrict the number of publication records per request. The default value is 50, if no value is specified. Maximum allowed value is 500.
    sort_fieldUsers can specify the sort field in the payload to sort the result by a specific field.
    sort_orderUsers can set this parameter to apply the sort order as ascending (asc) or descending (desc).
    Payload CriteriaHow to Use
    pmidsOne or more comma separated PMIDs in a square bracket to retrieve all publications associated with any of the PMIDs passed.
    Examples:
    { "criteria": { "pmids": [33298401, 33105091, 33205613] } }
    appl_idsOne or more comma separated application IDs in a square bracket to retrieve all publications associated with any of the application IDs passed.
    Examples:
    { "criteria": { "appl_ids": [10188551, 10098333, 10082298] } }
    core_project_numsOne or more comma separated core project number in a square bracket to retrieve all publications associated with any of the core project numbers passed.
    Examples:
    { "criteria": { "core_project_nums": ["UG1HD078437"] } }

    Search Project Number By Wildcard: The project number can be searched by wildcard (*) for zero or more occurrence.
    Examples:
    { "criteria": { "core_project_nums": [ "5UG1HD0784*"] } }

    Output for Search Endpoint

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

    Data Elements

    The Search API will return the set of data elements shown in the table below. This list is based on the current Export capability in NIH RePORTER.

    CategoryData Elements
    PublicationsCore Project Number
    PMID
    Latest Application ID