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,
|
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:
|
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:
|
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:
|
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 |