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 Group Data 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
  • Full Funding Opportunity Announcement
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
Separator Purpose
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 FOAs are specified as list: "foa":["RFA-DA-18-020","PAR-18-218","PAR-18-219"]
Payload Property Description
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_fields Users 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_fields Users 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" ]
offset Users 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.
limit Users 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_field Users can specify the sort field in the payload to sort the result by a specific field.
sort_order Users can set this parameter to apply the sort order as ascending (asc) or descending (desc).
search_id Search 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"}
url A 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 Criteria How to Use
use_relevance If 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_years One 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] } }
include_active_projects Return the result with active projects or ignore them. It takes true or false boolean value.

Examples:
{ "criteria": { "include_active_projects": true } }
pi_names One 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_names One 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_names One 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_match Since 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_ids One 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_cities One 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_states US 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_nums One 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_split Pass 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_categories One 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_mechanism One 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","OT","UK","CP"] } }
advanced_text_search Users 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_countries One 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_ids One 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] } }
agencies One 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_admin Pass the true or false value to filter the projects for admin agency status.

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

Example:
{ "criteria": { "is_agency_funding": true } }
activity_codes One 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_types One 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"] } }
dept_types One 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_dists One 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"] } }
foa One or more comma separated foa in a square bracket to retrieve all projects associated with any of the foa passed.

Example:
{ "criteria": { foa:[ "RFA-DA-18-020", "PAR-18-218",] } }
project_start_date Pass 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_date Pass 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_type One 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_date Users 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_range Users 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_subprojects Pass 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_only Pass 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_only Pass 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_only Pass 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_response Enter 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_added Pass 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.

Category Data Elements
Project Details IC
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
Personnel Principal Investigators
Program Officers
Funded Organization Congressional District
Organization Type
Organization Name
Organization City
Organization State
Organization ZIP
Organization Country
Project Funding Award Notice Date
Fiscal Year
Funding Opportunity Announcement
Award Amount
NIH COVID-19 Response
Project Details IC
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
Study Section SRG Code
SRG Flex
SRA Designator Code
SRA Flex Code
Group Code
Study Section Name
Personnel Principal Investigators
Program Officers
Funded Organization Congressional 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 Funding Award Notice Date
Fiscal Year
Funding Opportunity Announcement
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
Separator Purpose
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 FOAs are specified as list: "core_project_nums":["T32GM062754","U01HL136297","F31HL149358"]
Payload Property Description
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, ...]’
offset Users 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.
limit Users 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_field Users can specify the sort field in the payload to sort the result by a specific field.
sort_order Users can set this parameter to apply the sort order as ascending (asc) or descending (desc).
Payload Criteria How to Use
pmids One 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_ids One 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_nums One 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.

Category Data Elements
Publications Core Project Number
PMID
Latest Application ID