openapi: 3.0.3
info:
  title: National Science Foundation Awards API
  description: >-
    The NSF Research Spending and Results Web API provides programmatic access
    to the award search functionality available through Research.gov. The API
    exposes how federal research dollars are being spent, what research is
    being performed, and project outcomes that result from NSF-funded work.
  version: 1.0.0
  contact:
    name: NSF Developer Resources
    url: https://www.nsf.gov/developer
servers:
  - url: https://api.nsf.gov/services/v1
    description: Production
paths:
  /awards.{format}:
    get:
      summary: Search awards
      description: Search NSF awards using keyword, awardee, location, program, date, and amount filters.
      parameters:
        - name: format
          in: path
          required: true
          schema:
            type: string
            enum: [json, xml]
        - name: keyword
          in: query
          schema: { type: string }
          description: Free-text search supporting Boolean AND, OR, NOT.
        - name: rpp
          in: query
          schema: { type: integer, minimum: 1, maximum: 25, default: 25 }
          description: Results per page.
        - name: offset
          in: query
          schema: { type: integer, default: 1 }
          description: Starting record offset for pagination.
        - name: sortKey
          in: query
          schema:
            type: string
            enum: [awardNumber, awardTitle, nsfOrganization, startDate]
        - name: sortDirection
          in: query
          schema:
            type: string
            enum: [asc, desc]
        - name: dateStart
          in: query
          schema: { type: string }
          description: Award date start (mm/dd/yyyy).
        - name: dateEnd
          in: query
          schema: { type: string }
        - name: startDateStart
          in: query
          schema: { type: string }
        - name: startDateEnd
          in: query
          schema: { type: string }
        - name: expDateStart
          in: query
          schema: { type: string }
        - name: expDateEnd
          in: query
          schema: { type: string }
        - name: estimatedTotalAmtFrom
          in: query
          schema: { type: number }
        - name: estimatedTotalAmtTo
          in: query
          schema: { type: number }
        - name: fundsObligatedAmtFrom
          in: query
          schema: { type: number }
        - name: fundsObligatedAmtTo
          in: query
          schema: { type: number }
        - name: awardeeName
          in: query
          schema: { type: string }
        - name: awardeeCity
          in: query
          schema: { type: string }
        - name: awardeeStateCode
          in: query
          schema: { type: string }
        - name: awardeeZipCode
          in: query
          schema: { type: string }
        - name: perfCity
          in: query
          schema: { type: string }
        - name: perfStateCode
          in: query
          schema: { type: string }
        - name: perfLocation
          in: query
          schema: { type: string }
        - name: pdPIName
          in: query
          schema: { type: string }
        - name: coPDPI
          in: query
          schema: { type: string }
        - name: poName
          in: query
          schema: { type: string }
        - name: org_code_dir
          in: query
          schema: { type: string }
        - name: org_code_div
          in: query
          schema: { type: string }
        - name: progEleCode
          in: query
          schema: { type: string }
        - name: ActiveAwards
          in: query
          schema: { type: boolean }
        - name: ExpiredAwards
          in: query
          schema: { type: boolean }
        - name: histAwd
          in: query
          schema: { type: boolean }
        - name: transType
          in: query
          schema: { type: string }
        - name: callback
          in: query
          schema: { type: string }
          description: JSONP callback name (when format is json).
      responses:
        '200':
          description: Paginated list of award records with metadata.
  /awards/{id}.{format}:
    get:
      summary: Retrieve a single award
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
          description: NSF award number.
        - name: format
          in: path
          required: true
          schema:
            type: string
            enum: [json, xml]
      responses:
        '200':
          description: Award detail record.
  /awards/{id}/projectoutcomes.{format}:
    get:
      summary: Retrieve project outcomes for an award
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: format
          in: path
          required: true
          schema:
            type: string
            enum: [json, xml]
      responses:
        '200':
          description: Project outcomes report for the award.
components: {}