openapi: 3.1.0
info:
  title: SAMHSA Behavioral Health Treatment Services Locator API
  description: >-
    The SAMHSA Behavioral Health Treatment Services Locator API provides search access to
    over 14,000 substance use disorder and mental health treatment facilities across the
    United States. The API powers findtreatment.gov and allows developers to build
    treatment locator tools for their communities.
  version: "2.0"
  contact:
    name: SAMHSA
    url: https://www.samhsa.gov/find-help/national-helpline
  license:
    name: Public Domain (US Government)
    url: https://www.usa.gov/government-works
  x-agency: Substance Abuse and Mental Health Services Administration
  x-department: Department of Health and Human Services
servers:
  - url: https://findtreatment.gov/locator/listing
    description: SAMHSA Treatment Locator API

tags:
  - name: Treatment Facilities
    description: Search and retrieve behavioral health treatment facility listings
  - name: Locations
    description: Location-based facility search

paths:
  /listing:
    get:
      operationId: searchTreatmentFacilities
      summary: Search Treatment Facilities
      description: >-
        Search for substance use disorder and mental health treatment facilities
        by location, service type, payment options, and other criteria. Returns
        paginated results with facility contact information and services.
      tags:
        - Treatment Facilities
      parameters:
        - name: sAddr
          in: query
          required: false
          schema:
            type: string
          description: "Street address to search near"
        - name: sCity
          in: query
          required: false
          schema:
            type: string
          description: "City to search in"
        - name: sState
          in: query
          required: false
          schema:
            type: string
          description: "Two-letter state abbreviation (e.g., CA, TX)"
        - name: sZip
          in: query
          required: false
          schema:
            type: string
          description: "ZIP code to search near"
        - name: sDistance
          in: query
          required: false
          schema:
            type: integer
            default: 100
          description: "Search radius in miles"
        - name: sCatCode
          in: query
          required: false
          schema:
            type: string
          description: "Category code: SA (substance abuse), MH (mental health), CO (co-occurring)"
        - name: sType
          in: query
          required: false
          schema:
            type: string
          description: "Facility type code"
        - name: sService
          in: query
          required: false
          schema:
            type: string
          description: "Service type code (e.g., detox, residential, outpatient)"
        - name: sMedicaid
          in: query
          required: false
          schema:
            type: string
            enum: ["Y", "N"]
          description: "Filter for Medicaid-accepting facilities"
        - name: sMedicare
          in: query
          required: false
          schema:
            type: string
            enum: ["Y", "N"]
          description: "Filter for Medicare-accepting facilities"
        - name: sSlidingFee
          in: query
          required: false
          schema:
            type: string
            enum: ["Y", "N"]
          description: "Filter for sliding-scale fee facilities"
        - name: sNoFee
          in: query
          required: false
          schema:
            type: string
            enum: ["Y", "N"]
          description: "Filter for no-cost treatment facilities"
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
          description: "Page number for paginated results"
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            default: 20
          description: "Number of results per page"
      responses:
        '200':
          description: "Treatment facility search results"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TreatmentFacilitySearchResponse'
        '400':
          description: "Bad request - invalid parameters"
        '500':
          description: "Internal server error"

components:
  schemas:
    TreatmentFacility:
      type: object
      description: "A behavioral health treatment facility"
      properties:
        name1:
          type: string
          description: "Primary facility name"
        name2:
          type: string
          description: "Secondary facility name or DBA"
        street1:
          type: string
          description: "Street address line 1"
        street2:
          type: string
          description: "Street address line 2"
        city:
          type: string
          description: "City"
        state:
          type: string
          description: "Two-letter state abbreviation"
        zip:
          type: string
          description: "ZIP code"
        phone:
          type: string
          description: "Main phone number"
        websiteUrl:
          type: string
          format: uri
          description: "Facility website"
        latitude:
          type: number
          description: "Geographic latitude"
        longitude:
          type: number
          description: "Geographic longitude"
        distMiles:
          type: number
          description: "Distance in miles from search location"
        category:
          type: string
          description: "Service category (substance abuse, mental health, co-occurring)"
        typeDescription:
          type: string
          description: "Facility type description"
        services:
          type: array
          items:
            type: string
          description: "List of services offered"
        paymentOptions:
          type: array
          items:
            type: string
          description: "Accepted payment methods"
        medicaid:
          type: string
          enum: ["Y", "N"]
          description: "Whether facility accepts Medicaid"
        medicare:
          type: string
          enum: ["Y", "N"]
          description: "Whether facility accepts Medicare"
        slidingFee:
          type: string
          enum: ["Y", "N"]
          description: "Whether facility offers sliding scale fees"
        noFee:
          type: string
          enum: ["Y", "N"]
          description: "Whether facility offers free treatment"

    TreatmentFacilitySearchResponse:
      type: object
      properties:
        facilities:
          type: array
          items:
            $ref: '#/components/schemas/TreatmentFacility'
        totalCount:
          type: integer
          description: "Total number of matching facilities"
        page:
          type: integer
          description: "Current page number"
        pageSize:
          type: integer
          description: "Results per page"
        searchLocation:
          type: object
          properties:
            latitude:
              type: number
            longitude:
              type: number
            address:
              type: string