About the API

    Purpose

    Federal RePORTER APIs are designed to expose relevant scientific 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 users are developers, solution architects, and technical architects. Business users such as CIOs, program managers, project managers or other technology executives are other potential audience who might be interested in understanding the value of Federal RePORTER API for their projects before involving their technical teams.

    Constraints/Limitations

    1. Federal RePORTER APIs will not support fuzzy search, proximity search or range based search in the initial roll out.
    2. Current set of APIs do not expose following data categories,
      • Patents
      • Publications
      • News
      • Similar Projects
    3. The API service will be available except during pre-scheduled maintenance window. Appropriate maintenance messages will be posted in advance on the API site.
    4. 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 between 9:00 PM and 5:00 AM Eastern time during weekdays. Failure to comply with this policy may result in an IP address being blocked from accessing the API service. For any questions regarding API calls, feel free to 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.

    Get Projects Endpoint: Following data elements as an input.

    • 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: Only one project record is retrieved with each API call.

    Fetch Projects by SM Appl Id(s) Endpoint: Following data element is accepted as an input.

    • smApplIds: Users can enter one or more SM Appl Ids as a comma separated array of integers.

    Fetch Projects by Project Numbers(s) Endpoint: Following data element is accepted as an input.

    • projNumber(s): 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: Fetch based API returns a maximum of 50 project records at a time. It is users’ responsibility to keep track of the SM Appl Ids or Project Numbers for which the data is already retrieved.

    Search Projects Endpoint: Following data elements are accepted as an input.

    • projectNumber: Complete Project Number or a partial one with wild card option. Minimum of 3 characters must be provided for a Project Number.
    • 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:
      • 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.
      • 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.
    • 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.
    • agency: One or more comma separated agency codes to retrieve all the projects that are associated with each of the agency. For simplicity, this parameter can accept codes for a US government department, or a federal agency or ICs (Institute Center). To see the complete list of valid agency codes, please click here.
      Note: when NIH is one of the value passed then there is no need to include any of its IC as an agency parameter. API shall return projects associated with all the ICs under NIH. Similarly, when HHS is used then API will return projects associated with all the agencies and ICs under HHS.
    • piName: One or more semi-colon separated project investigator (PI) names to retrieve all the projects that are associated with any of the PI names passed. 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.
    • Users can combine one or more of project number, text, fy, agency and piName within the same API call. For example, to retrieve projects referencing both “cancer” and “lung” and having “R01” string in the project number with fiscal year as 2015 and 2014, agency values as NIH and EPA and piName as Smith use this format query=projectNumber:*R01*$text:cancer lung$fy:2015,2014$agency:nih,epa$piName:smith
    • offset: Users can set the starting counter for each page. By default, it starts at 1 for the first page.
    • limit: Users can set this parameter to restrict number of project records per page. Maximum allowed value is 50, which is also the default if no value is specified. 

    Output: Search based API returns a certain number of project records per page based on the values set for the parameters “offset” and “limit”.

    All three type of APIs (single project, fetch and search) will return a content type of XML or JSON object as an output with data elements as shown in the table below. This list is based on the current Export capability in Federal RePORTER. (Note: For exact syntax, please refer to the API Endpoints section below)

    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

    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. 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.