openapi: 3.2.0
info:
  title: General Services Administration Search API
  version: 2.0
  description: 'Operations tagged search across 2 of this provider''s published API definitions: general-services-administration-searchgov-clicks-openapi.yaml, general-services-administration-searchgov-results-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.gsa.gov/technology/searchgov/v2
tags:
- name: Search
paths:
  /clicks/:
    get:
      summary: Click tracking
      description: This endpoint allows you to send in click data.
      parameters:
      - name: affiliate
        in: query
        description: The unique site handle you created for the affiliate site when you set up your search experience. Find your site handle on the Settings page in the Admin Center.
        required: true
        schema:
          type: string
          format: string
      - name: access_key
        in: query
        description: The site’s unique API access key that was automatically generated when you set up your search experience. Find your access key on the API Access Key page in the Admin Center.
        required: true
        schema:
          type: integer
          format: integer
          default: 0
      - name: query
        in: query
        description: The query entered by a user via your site’s search box, which resulted in a click.
        required: true
        schema:
          type: string
          format: string
      - name: url
        in: query
        description: The URL of the result that was clicked on search results page.
        required: true
        schema:
          type: string
          format: string
      - name: position
        in: query
        description: The ranked position of the clicked result, such as 1 or 2.
        required: true
        schema:
          type: integer
          format: string
      - name: module_code
        in: query
        description: The module code of the clicked result. Must be a valid module code.
        required: true
        schema:
          type: integer
          format: integer
          default: 20
      - name: client_ip
        in: query
        description: The IP address of the user who clicked on the result.
        required: false
        schema:
          type: string
          format: string
      - name: user_agent
        in: query
        description: The user agent of the user who clicked on the result.
        required: false
        schema:
          type: string
          format: string
      - name: referrer
        in: query
        description: The URL of the page the user was on when clicking on the result.
        required: false
        schema:
          type: string
          format: string
      tags:
      - Search
      responses:
        '200':
          description: Successfully retrieved click data.
        '400':
          description: Query cannot be blank.
        '401':
          description: Errors with inputs, such as an unparseable URL or invalid affiliate site, access key, or module code.
      security:
      - ApiKeyAuth: []
      operationId: getClicks
      x-operation-id-source: derived
    servers:
    - url: https://api.gsa.gov/technology/searchgov/v2
  /results/i14y:
    get:
      summary: Search results
      description: This endpoint returns search results.
      parameters:
      - name: affiliate
        in: query
        description: The unique site handle you created for the affiliate site when you set up your search experience. Find your site handle on the Settings page in the Admin Center.
        required: true
        schema:
          type: string
          format: string
      - name: access_key
        in: query
        description: The site’s unique API access key that was automatically generated when you set up your search experience. Find your access key on the API Access Key page in the Admin Center.
        required: true
        schema:
          type: string
          format: string
      - name: query
        in: query
        description: The query entered by a user via your site’s search box.
        required: true
        schema:
          type: string
          format: string
      - name: enable_highlighting
        in: query
        description: By default, we highlight all relevant, matched keywords in the search results by setting this value to ‘true’. The opening Unicode character for highlighting is ‘U+E000’ and the closing character is ‘U+E001’. You need to decide how to display these characters — whether as bold, italic, or another style. You can use ‘false’ to remove the highlighting.
        required: false
        schema:
          type: boolean
          format: string
          default: true
      - name: limit
        in: query
        description: By default, we return 20 results. You can specify between 1 and 50 results.
        required: false
        schema:
          type: integer
          format: integer
          default: 20
      - name: offset
        in: query
        description: By default, we set the offset to 0. The offset defines the number of results skipped from the first result. You can use the offset parameter to implement pagination. The maximum value is 999.
        required: false
        schema:
          type: integer
          format: integer
          default: 0
      - name: sort_by
        in: query
        description: By default, we return results sorted by ‘relevance’. You can also sort by ‘date’.
        required: false
        schema:
          type: string
          format: string
          default: relevance
      - name: sitelimit
        in: query
        description: By default, we return all results within the scope of the domains you set up in the Admin Center. You can use the sitelimit parameter to limits the results to only content within specific subdomains or subfolders. You can include multiple sitelimit values using a space-separated list. The sitelimit values must be within the scope of the domains set up in the Admin Center.
        required: false
        schema:
          type: string
          format: string
      - name: api_key
        in: query
        description: By default, you can make 1,000 requests per hour using your SearchGov access key. If you need higher rate limits, please email the SearchGov team for information on how to set up an API.Data.gov API key to increase these limits.
        required: false
        schema:
          type: string
          format: string
      tags:
      - Search
      responses:
        '200':
          description: The search results
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                  - $ref: '#/components/schemas/query'
                  - $ref: '#/components/schemas/web'
                  - $ref: '#/components/schemas/text_best_bets'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                type: string
                items:
                  $ref: '#/components/schemas/Error'
      operationId: getResultsI14y
      x-operation-id-source: derived
    servers:
    - url: https://api.gsa.gov/technology/searchgov/v2
components:
  schemas:
    text_best_bets:
      type: array
      properties:
        id:
          type: integer
          description: ID of the best bet
        title:
          type: string
          description: Title of the best bet
        url:
          type: string
          description: URL of the best bet
        description:
          type: string
          description: Description of the best bet
    web:
      type: array
      description: An array of data about the web results
      properties:
        total:
          type: integer
          description: Total number of results available
        next_offset:
          type: integer
          description: Offset for the subsequent results.
        results:
          type: array
          description: Results are an array of arrays, each containing the properties listed below.
          properties:
            title:
              type: string
              description: Title of the document
            url:
              type: string
              description: URL of the document
            snippet:
              type: string
              description: Summary of the document
            publication_date:
              type: string
              format: date
              description: Publication date of the document (not available on commercial results)
            thumbnail_url:
              type: string
              description: URL of the Open Graph Image of the document
            updated_date:
              type: string
              format: date
              description: Last updated date of the document
        aggregations:
          type: array
          description: An array of facet objects containing the number of documents associated with each facet value. Within each item, an object representing a facet field (ex. content_type) will have the properties listed below.
          properties:
            agg_key:
              type: string
              description: Name of the facet value
            doc_count:
              type: integer
              description: Number of documents matching the facet value
            to:
              type: integer
              description: Upper bound of date range in Unix epoch date format.
            from:
              type: integer
              description: Lower bound of date range in Unix epoch date format.
            to_as_string:
              type: string
              format: date
              description: Upper bound of date range in  m/d/YYYY format.
            from_as_string:
              type: string
              format: date
              description: Lower bound of date range in  m/d/YYYY format.
    query:
      type: string
      description: We return the query to you for use in the results page display
    Error:
      type: string
      description: The issue with your request.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
x-refined-from:
- general-services-administration-searchgov-clicks-openapi.yaml
- general-services-administration-searchgov-results-openapi.yaml