openapi: 3.1.0
info:
  title: SAMHSA Behavioral Health Treatment Services Locator Treatment Facilities 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
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