[Issue #1167] Add filtering to the search endpoint

api/openapi.generated.yml

@@ -314,6 +314,47 @@ paths:
           application/json:
             schema:
               $ref: '#/components/schemas/OpportunitySearchRequest'
+            examples:
+              example1:
+                summary: No filters
+                value:
+                  pagination:
+                    order_by: opportunity_id
+                    page_offset: 1
+                    page_size: 25
+                    sort_direction: ascending
+              example2:
+                summary: All filters
+                value:
+                  query: research
+                  filters:
+                    agency:
+                      one_of:
+                      - US-ABC
+                      - HHS
+                    applicant_type:
+                      one_of:
+                      - state_governments
+                      - county_governments
+                      - individuals
+                    funding_category:
+                      one_of:
+                      - recovery_act
+                      - arts
+                      - natural_resources
+                    funding_instrument:
+                      one_of:
+                      - cooperative_agreement
+                      - grant
+                    opportunity_status:
+                      one_of:
+                      - forecasted
+                      - posted
+                  pagination:
+                    order_by: opportunity_id
+                    page_offset: 1
+                    page_size: 25
+                    sort_direction: descending
       security:
       - ApiKeyAuth: []
   /v0/opportunities/{opportunity_id}:
@@ -727,6 +768,130 @@ components:
           type: string
           format: date-time
           readOnly: true
+    FundingInstrumentFilter:
+      type: object
+      properties:
+        one_of:
+          type: array
+          items:
+            enum:
+            - cooperative_agreement
+            - grant
+            - procurement_contract
+            - other
+            type:
+            - string
+    FundingCategoryFilter:
+      type: object
+      properties:
+        one_of:
+          type: array
+          items:
+            enum:
+            - recovery_act
+            - agriculture
+            - arts
+            - business_and_commerce
+            - community_development
+            - consumer_protection
+            - disaster_prevention_and_relief
+            - education
+            - employment_labor_and_training
+            - energy
+            - environment
+            - food_and_nutrition
+            - health
+            - housing
+            - humanities
+            - infrastructure_investment_and_jobs_act
+            - information_and_statistics
+            - income_security_and_social_services
+            - law_justice_and_legal_services
+            - natural_resources
+            - opportunity_zone_benefits
+            - regional_development
+            - science_technology_and_other_research_and_development
+            - transportation
+            - affordable_care_act
+            - other
+            type:
+            - string
+    ApplicantTypeFilter:
+      type: object
+      properties:
+        one_of:
+          type: array
+          items:
+            enum:
+            - state_governments
+            - county_governments
+            - city_or_township_governments
+            - special_district_governments
+            - independent_school_districts
+            - public_and_state_institutions_of_higher_education
+            - private_institutions_of_higher_education
+            - federally_recognized_native_american_tribal_governments
+            - other_native_american_tribal_organizations
+            - public_and_indian_housing_authorities
+            - nonprofits_non_higher_education_with_501c3
+            - nonprofits_non_higher_education_without_501c3
+            - individuals
+            - for_profit_organizations_other_than_small_businesses
+            - small_businesses
+            - other
+            - unrestricted
+            type:
+            - string
+    OpportunityStatusFilter:
+      type: object
+      properties:
+        one_of:
+          type: array
+          items:
+            enum:
+            - forecasted
+            - posted
+            - closed
+            - archived
+            type:
+            - string
+    AgencyFilter:
+      type: object
+      properties:
+        one_of:
+          type: array
+          items:
+            type: string
+            minLength: 2
+            example: US-ABC
+    OpportunitySearchFilter:
+      type: object
+      properties:
+        funding_instrument:
+          type:
+          - object
+          allOf:
+          - $ref: '#/components/schemas/FundingInstrumentFilter'
+        funding_category:
+          type:
+          - object
+          allOf:
+          - $ref: '#/components/schemas/FundingCategoryFilter'
+        applicant_type:
+          type:
+          - object
+          allOf:
+          - $ref: '#/components/schemas/ApplicantTypeFilter'
+        opportunity_status:
+          type:
+          - object
+          allOf:
+          - $ref: '#/components/schemas/OpportunityStatusFilter'
+        agency:
+          type:
+          - object
+          allOf:
+          - $ref: '#/components/schemas/AgencyFilter'
     OpportunityPagination:
       type: object
       properties:
@@ -761,6 +926,15 @@ components:
     OpportunitySearchRequest:
       type: object
       properties:
+        query:
+          type: string
+          description: Query string which searches against several text fields
+          example: research
+        filters:
+          type:
+          - object
+          allOf:
+          - $ref: '#/components/schemas/OpportunitySearchFilter'
         pagination:
           type:
           - object
@@ -784,17 +958,6 @@ components:
     OpportunitySummary:
       type: object
       properties:
-        opportunity_status:
-          description: The current status of the opportunity
-          example: !!python/object/apply:src.constants.lookup_constants.OpportunityStatus
-          - posted
-          enum:
-          - forecasted
-          - posted
-          - closed
-          - archived
-          type:
-          - string
         summary_description:
           type: string
           description: The summary of the opportunity
@@ -803,10 +966,15 @@ components:
           type: boolean
           description: Whether or not the opportunity has a cost sharing/matching
             requirement
+        is_forecast:
+          type: boolean
+          description: Whether the opportunity is forecasted, that is, the information
+            is only an estimate and not yet official
+          example: false
         close_date:
           type: string
           format: date
-          description: The date that the opportunity will close
+          description: The date that the opportunity will close - only set if is_forecast=False
         close_date_description:
           type: string
           description: Optional details regarding the close date
@@ -844,6 +1012,35 @@ components:
           type: string
           description: The text to display for the additional_info_url link
           example: Click me for more info
+        forecasted_post_date:
+          type: string
+          format: date
+          description: Forecasted opportunity only. The date the opportunity is expected
+            to be posted, and transition out of being a forecast
+        forecasted_close_date:
+          type: string
+          format: date
+          description: Forecasted opportunity only. The date the opportunity is expected
+            to be close once posted.
+        forecasted_close_date_description:
+          type: string
+          description: Forecasted opportunity only. Optional details regarding the
+            forecasted closed date.
+          example: Proposals will probably be due on this date
+        forecasted_award_date:
+          type: string
+          format: date
+          description: Forecasted opportunity only. The date the grantor plans to
+            award the opportunity.
+        forecasted_project_start_date:
+          type: string
+          format: date
+          description: Forecasted opportunity only. The date the grantor expects the
+            award recipient should start their project
+        fiscal_year:
+          type: integer
+          description: Forecasted opportunity only. The fiscal year the project is
+            expected to be funded and launched
         funding_category_description:
           type: string
           description: Additional information about the funding category
@@ -877,63 +1074,6 @@ components:
           type: string
           description: The text for the link to the agency email address
           example: Click me to email the agency
-    Opportunity:
-      type: object
-      properties:
-        opportunity_id:
-          type: integer
-          readOnly: true
-          description: The internal ID of the opportunity
-          example: 12345
-        opportunity_number:
-          type: string
-          description: The funding opportunity number
-          example: ABC-123-XYZ-001
-        opportunity_title:
-          type: string
-          description: The title of the opportunity
-          example: Research into conservation techniques
-        agency:
-          type: string
-          description: The agency who created the opportunity
-          example: US-ABC
-        category:
-          description: The opportunity category
-          example: !!python/object/apply:src.constants.lookup_constants.OpportunityCategory
-          - discretionary
-          enum:
-          - discretionary
-          - mandatory
-          - continuation
-          - earmark
-          - other
-          type:
-          - string
-        category_explanation:
-          type: string
-          description: Explanation of the category when the category is 'O' (other)
-          example: null
-        revision_number:
-          type: integer
-          description: The current revision number of the opportunity, counting starts
-            at 0
-          example: 0
-        modified_comments:
-          type: string
-          description: Details regarding what modification was last made
-          example: null
-        opportunity_assistance_listings:
-          type: array
-          items:
-            type:
-            - object
-            allOf:
-            - $ref: '#/components/schemas/OpportunityAssistanceListing'
-        summary:
-          type:
-          - object
-          allOf:
-          - $ref: '#/components/schemas/OpportunitySummary'
         funding_instruments:
           type: array
           items:
@@ -999,6 +1139,65 @@ components:
             - unrestricted
             type:
             - string
+    Opportunity:
+      type: object
+      properties:
+        opportunity_id:
+          type: integer
+          readOnly: true
+          description: The internal ID of the opportunity
+          example: 12345
+        opportunity_number:
+          type: string
+          description: The funding opportunity number
+          example: ABC-123-XYZ-001
+        opportunity_title:
+          type: string
+          description: The title of the opportunity
+          example: Research into conservation techniques
+        agency:
+          type: string
+          description: The agency who created the opportunity
+          example: US-ABC
+        category:
+          description: The opportunity category
+          example: !!python/object/apply:src.constants.lookup_constants.OpportunityCategory
+          - discretionary
+          enum:
+          - discretionary
+          - mandatory
+          - continuation
+          - earmark
+          - other
+          type:
+          - string
+        category_explanation:
+          type: string
+          description: Explanation of the category when the category is 'O' (other)
+          example: null
+        opportunity_assistance_listings:
+          type: array
+          items:
+            type:
+            - object
+            allOf:
+            - $ref: '#/components/schemas/OpportunityAssistanceListing'
+        summary:
+          type:
+          - object
+          allOf:
+          - $ref: '#/components/schemas/OpportunitySummary'
+        opportunity_status:
+          description: The current status of the opportunity
+          example: !!python/object/apply:src.constants.lookup_constants.OpportunityStatus
+          - posted
+          enum:
+          - forecasted
+          - posted
+          - closed
+          - archived
+          type:
+          - string
         created_at:
           type: string
           format: date-time