openapi: 3.0.0
info:
  title: Search.gov Results API
  description: Search.gov is a service of the General Services Administration, providing search engine capability to federal agencies for their public websites. This API This API exposes all relevant Search.gov results “modules” in a single JSON call.
  version: 2.0

paths:
  /results/i14y:
    get:
      summary: Search Results
      description: 'This endpoint returns search results.'
      parameters:
        - name: affiliate
          in: query
          description: 'Site handle.'
          required: true
          schema:
              type: string
              format: string
        - name: access_key
          in: query
          description: 'The Search.gov key used to access the API'
          required: true
          schema:
            type: string
            format: string
        - name: query
          in: query
          description: 'Search term.'
          required: false
          schema:
            type: string
            format: string
        - name: enable_highlighting
          in: query
          description: 'Enables or disables the highlighting of keywords in the results. The default is "true" so use "false" to disable highlighting.'
          required: false
          schema:
            type: boolean
            format: string
            default: true
        - name: limit
          in: query
          description: 'Defines the number of results to return. The default is 20, but you can specify between 1 and 50 results.'
          required: false
          schema:
            type: integer
            format: integer
            default: 20
        - name: offset
          in: query
          description: 'Defines the number of results you want to skip from the first result. The offset is used for implementing pagination. The default is 0 and the maximum is 999.'
          required: false
          schema:
            type: integer
            format: integer
            default: 0
        - name: sort_by
          in: query
          description: Allowed variables are date and relevance. The default sort is relevance. Add `sort_by = date` to sort by date.
          required: false
          schema:
            type: string
            format: string
            default: relevance
        - name: sitelimit
          in: query
          description: 'Allows you to limit the results by subdomains or subfolders. You can limit to multiple locations using a space-separated list (ex. `sitelimit=search.gov/about search.gov/get-started`)'
          required: false
          schema:
            type: string
            format: string
        - name: include_facets
          in: query
          description: "Allows you to enable facet features to be returned in the API response."
          required: false
          schema:
            type: boolean
        - name: audience
          in: query
          description: 'Allows you to filter results based on the Audience field. Accepts a comma-separated list of strings.'
          required: false
          schema:
            type: string
            format: string
        - name: content_type
          in: query
          description: 'Allows you to filter results based on the Content Type field. Accepts a comma-separated list of strings.'
          required: false
          schema:
            type: string
            format: string
        - name: created_until
          in: query
          description: 'Allows you to set an upper bound for the date the document was created.'
          required: false
          schema:
            type: string
            format: date
            description: The day in YYYY-MM-DD format.
        - name: created_since
          in: query
          description: 'Allows you to set an lower bound for the date the document was created.'
          required: false
          schema:
            type: string
            format: date
            description: The day in YYYY-MM-DD format.
        - name: mime_type
          in: query
          description: 'Allows you to filter results based on the Mimetype field. Accepts a comma-separated list of strings.'
          required: false
          schema:
            type: string
            format: string
        - name: tags
          in: query
          description: 'Allows you to filter results based on the Tags field. Accepts a comma-separated list of strings.'
          required: false
          schema:
            type: string
            format: string
        - name: searchgov_custom1
          in: query
          description: 'Allows you to filter results based on the Search.gov Custom 1 field. Accepts a comma-separated list of strings.'
          required: false
          schema:
            type: string
            format: string
        - name: searchgov_custom2
          in: query
          description: 'Allows you to filter results based on the Search.gov Custom 2 field. Accepts a comma-separated list of strings.'
          required: false
          schema:
            type: string
            format: string
        - name: searchgov_custom3
          in: query
          description: 'Allows you to filter results based on the Search.gov Custom 3 field. Accepts a comma-separated list of strings.'
          required: false
          schema:
            type: string
            format: string
        - name: updated_since
          in: query
          description: 'Allows you to set an upper bound for the date the document was last updated.'
          required: false
          schema:
            type: string
            format: date
            description: The day in YYYY-MM-DD format.
        - name: updated_until
          in: query
          description: 'Allows you to set an lower bound for the date the document was last updated.'
          required: false
          schema:
            type: string
            format: date
            description: The day in YYYY-MM-DD format.
      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'
                  - $ref: '#/components/schemas/graphic_best_bets'
                  - $ref: '#/components/schemas/health_topics'
                  - $ref: '#/components/schemas/job_openings'
                  - $ref: '#/components/schemas/federal_register_documents'
                  - $ref: '#/components/schemas/related_search_terms'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                type: string
                items:
                  $ref: '#/components/schemas/Error'

components:
  schemas:   
    Error:
      type: string
      description: The issue with your request.
    query:
      type: string
      description: We return the query to you for use in the results page display
    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.
        include_facets: 
          type: boolean
          description:  Returns "true" if facets are enabled, "false" if not.      
        spelling_correction: 
          type: string
          description:  Spelling correction for your search term.      
        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
            audience:
              type: string
              description: Audience of the document. Only included if a value for the field exists. 
            content_type:
              type: string
              description: Content type of the document. Only included if a value for the field exists. 
            mime_type:
              type: string
              description: MIME type of the document. Only included if a value for the field exists. 
            tags:
              type: array
              description: Tags associated with the document. Only included if a value for the field exists. 
            searchgov_custom1:
              type: array
              description: Search.gov custom field 1 content associated with the document. Only included if a value for the field exists. 
            searchgov_custom2:
              type: array
              description: Search.gov custom field 2 content associated with the document. Only included if a value for the field exists. 
            searchgov_custom3:
              type: array
              description: Search.gov custom field 3 content associated with the document. Only included if a value for the field exists. 
            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.



    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
    graphic_best_bets:
      type: array
      properties: 
        id:
          type: integer
          description: ID of the graphic best bet
        title:
          type: string
          description: Title of the graphic best bet 
        title_url:
          type: string
          description: URL of the graphic best bet
        image_url:
          type: string
          description: URL of the image
        image_alt_text:
          type: string
          description: Alternative text of the image
        links:
          type: array
          properties:
            title:
              type: string
              description: Title of the link
            url:
              type: string
              description: URL of the best bet link
    health_topics:
      type: array
      properties: 
        title:
          type: string
          description: Title of the health topic 
        url:
          type: string
          description: URL of the health topic
        snippet:
          type: string
          description: snippet of the health topic
        related_topics:
          type: array
          properties:
            title:
              type: string
              description: Title of the related topic
            url:
              type: string
              description: URL of the related topic
        related_sites:
          type: array
          properties:
            title:
              type: string
              description: Title of the related site
            url:
              type: string
              description: URL of the related site
    job_openings:
      type: array
      properties: 
        position_id:
          type: integer
          description: ID of the job opening 
        position_title:
          type: string
          description: Position title of the job opening
        position_uri:
          type: string
          description: URI of the job opening
        apply_uri:
          type: array
          properties:
            uri:
              type: string
              description: URI of the job opening      
        position_location_display:
          type: string
          description: Text of the position location
        position_location:
          type: array
          properties:
            location_name:
              type: string
              description: City/State of job location
            country_code:
              type: string
              description: Country of job location
            country_sub-division_code:
              type: string
              description: State or subdivision of job location
            longitude:
              type: number
              description: Longitude of job location
            latitude:
              type: number
              description: Latitude of job location
        organization_name:
          type: string
          description: Organization name of the job opening
        department_name:
          type: string
          description: Name of the department with opening
        sub_agency:
          type: string
          description: Name of the department's agency with opening
        job_category:
          type: array
          properties:
            title:
              type: string
              description: Title of the related topic
            url:
              type: string
              description: URL of the related topic
        job_grade:
          type: array
          properties:
            code:
              type: string
              description: Job code
        position_schedule:
          type: array
          properties:
            name:
              type: string
              description: Type of schedule for job
            code:
              type: string
              description: Code for job type
        position_offering_    type:
          type: array
          properties:
            name:
              type: string
              description: Position type (permanent or temporary)
            code:
              type: string
              description: Code for position type
        qualification_summary:
          type: string
          description: Summary of the job's required qualifications
        position_remuneration:
          type: array
          properties:
            minimum_range:
              type: string
              description: Minimum payment
            maximum_range:
              type: string
              description: Maximum payment
            rate_interval_code:
              type: string
              description: Frequency of pay listed above
        position_start_date:
          type: string
          description: Start date of the job opening
        position_end_date:
          type: string
          description: End date of the job opening
        publication_start_date:
          type: string
          description: Application start date
        appication_close_date:
          type: string
          description: Application close date
        position_formatted_  description:
          type: array
          properties:
            label:
              type: string
              description: Type of added formatting to job posting
            label_description:
              type: string
              description: Additional text for customizing posting
        user_area:
          type: array
          properties:
            details:
              type: array
              properties:
                job_summary:
                  type: string
                  description: Summary of the job
                who_may_apply:
                  type: array
                  properties:
                    name:
                      type: string
                    code:
                      type: string
                low_grade:
                  type: string
                high_grade:
                  type: string
                promotion_potential:
                  type: string
                hiring_path:
                  type: array
                  properties:
                    hiring_path:
                      type: string
                total_openings:
                  type: string
                  description: Total number of openings
                agency_marketing_statement:
                  type: string
                  description: Marketing information about the agency posting the job
                travel code:
                  type: string
                apply_online_url:
                  type: string
                  description: URL of the job application
                detail_status_url:
                  type: string
                  description: URL of job application status
            is_radial_search:
              type: boolean
        url:
          type: string
          description: URL for job details
        locations:
          type: array
          description: An array of locations
        minimum: 
          type: integer
          description: Minimum salary of the job opening
        maximum:
          type: integer
          description: Maximum salary of the job opening
        rate_interval_code:
          type: string
          description: Rate interval code of the job opening
        org_codes:
          type: string
          description: Organization codes
    federal_register_documents:
      type: array
      properties: 
        id:
          type: integer
          description: The ID of the document as known to usasearch
        document_number:
          type: string
          description: Document number of the federal register document 
        title:
          type: string
          description: Title
        url:
          type: string
          description: URL for Federal Register document.
        agency:
          type: array
          properties:
            agency_names:
              type: string
              description: agency names of the federal register document
        page_length:
          type: integer
          description: Page length of the federal register document
        start_page:
          type: integer
          description: Start page of the federal register document
        end_page:
          type: integer
          description: End page of the federal register document
        publication_date:
          type: string
          description: Publication date of the federal register document
        comments_close_date:
          type: string
          description: Comments close date of the federal register document
    related_search_terms:
      type: array
      description: An array of related search terms, which are based on recent, common searches on the your site. Users will need to render each of these into a link that would make a new API call with that query term as they query 
  
servers:
  - url: 'https://api.gsa.gov/technology/searchgov/v2'
