openapi: 3.0.3
info:
  title: USDA AMS MARS API (MyMarketNews) Offices Reports API
  description: The Market Analysis Reporting System (MARS) API provides programmatic access to USDA Agricultural Marketing Service agricultural market news data. The API allows users to automatically pull raw market news data including commodity prices, volume, and trade reports across livestock, dairy, fruits, vegetables, grains, and other agricultural commodities. Authentication via Basic auth with an API key is supported for registered users; no key is required for public access. All responses are in JSON format.
  version: v1.2
  contact:
    url: https://mymarketnews.ams.usda.gov
  x-generated-from: documentation
servers:
- url: https://marsapi.ams.usda.gov/services/v1.2
  description: MARS API v1.2
- url: https://marsapi.ams.usda.gov/services/v3.0
  description: MARS API v3.0
security: []
tags:
- name: Reports
  description: Agricultural market news reports across all commodity types
paths:
  /reports:
    get:
      operationId: listReports
      summary: USDA AMS List Reports
      description: Returns a list of all available market news reports. Each report has a unique Slug_ID and Slug_Name that serve as identifiers. Reports cover livestock, dairy, fruits, vegetables, grains, cotton, tobacco, poultry, and other agricultural commodities.
      tags:
      - Reports
      parameters:
      - name: q
        in: query
        description: Search query to filter reports by name or description.
        required: false
        schema:
          type: string
          example: cattle
      - name: allSections
        in: query
        description: Return all report sections (true/false).
        required: false
        schema:
          type: boolean
          example: true
      - name: dateType
        in: query
        description: Date type to filter by (published, report).
        required: false
        schema:
          type: string
          enum:
          - published
          - report
          example: published
      - name: startDate
        in: query
        description: Start date for filtering reports (YYYY-MM-DD).
        required: false
        schema:
          type: string
          format: date
          example: '2026-01-01'
      - name: endDate
        in: query
        description: End date for filtering reports (YYYY-MM-DD). Maximum 180 days from startDate.
        required: false
        schema:
          type: string
          format: date
          example: '2026-04-19'
      - name: slug_id
        in: query
        description: Filter by specific report slug ID.
        required: false
        schema:
          type: string
          example: '2451'
      - name: class
        in: query
        description: Filter by commodity class (e.g., Livestock, Dairy, Fruit/Veg).
        required: false
        schema:
          type: string
          example: Livestock
      - name: limit
        in: query
        description: Maximum number of records to return (max 100000).
        required: false
        schema:
          type: integer
          maximum: 100000
          example: 100
      - name: offset
        in: query
        description: Number of records to skip for pagination.
        required: false
        schema:
          type: integer
          example: 0
      - name: sort_by
        in: query
        description: Field to sort results by.
        required: false
        schema:
          type: string
          example: published_date
      - name: sort_order
        in: query
        description: Sort order (asc or desc).
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          example: desc
      responses:
        '200':
          description: A list of market news reports.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportsListResponse'
              examples:
                ListReports200Example:
                  summary: Default listReports 200 response
                  x-microcks-default: true
                  value:
                    results:
                    - slug_id: '2451'
                      slug_name: National Weekly Cattle Summary
                      report_date: '2026-04-18'
                      published_date: '2026-04-18T16:00:00Z'
                      commodity: Cattle
                      market_type: Weekly Summary
                      office: National
                      section_name: All Classes
                    stats:
                      count: 1
                      total: 500
        '400':
          description: Bad request. Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized. Invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /reports/{slug_id}:
    get:
      operationId: getReport
      summary: USDA AMS Get Report
      description: Returns market news data for a specific report identified by its unique slug_id. Returns the full report data including commodity prices, volumes, and trade information.
      tags:
      - Reports
      parameters:
      - name: slug_id
        in: path
        description: Unique identifier (Slug_ID) for the market news report.
        required: true
        schema:
          type: string
          example: '2451'
      - name: startDate
        in: query
        description: Start date for filtering data within the report (YYYY-MM-DD).
        required: false
        schema:
          type: string
          format: date
          example: '2026-01-01'
      - name: endDate
        in: query
        description: End date for filtering data (YYYY-MM-DD). Maximum 180 days from startDate.
        required: false
        schema:
          type: string
          format: date
          example: '2026-04-19'
      - name: limit
        in: query
        description: Maximum records to return.
        required: false
        schema:
          type: integer
          maximum: 100000
          example: 100
      - name: offset
        in: query
        description: Number of records to skip.
        required: false
        schema:
          type: integer
          example: 0
      responses:
        '200':
          description: Report data with commodity prices and market information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportDataResponse'
              examples:
                GetReport200Example:
                  summary: Default getReport 200 response
                  x-microcks-default: true
                  value:
                    results:
                    - slug_id: '2451'
                      slug_name: National Weekly Cattle Summary
                      report_date: '2026-04-18'
                      published_date: '2026-04-18T16:00:00Z'
                      commodity: Cattle
                      class: Slaughter
                      grade: Choice
                      head_count: 45000
                      price_per_cwt: 185.5
                      price_unit: CWT
                      region: National
                    stats:
                      count: 1
                      total: 1
        '404':
          description: Report not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Report:
      type: object
      title: Report
      description: A USDA AMS market news report entry.
      properties:
        slug_id:
          type: string
          description: Unique identifier for the report.
          example: '2451'
        slug_name:
          type: string
          description: Unique name for the report.
          example: National Weekly Cattle Summary
        report_date:
          type: string
          format: date
          description: Date the report data covers.
          example: '2026-04-18'
        published_date:
          type: string
          format: date-time
          description: Date and time the report was published.
          example: '2026-04-18T16:00:00Z'
        commodity:
          type: string
          description: Agricultural commodity covered by the report.
          example: Cattle
        market_type:
          type: string
          description: Type of market covered (Weekly Summary, Daily, etc.).
          example: Weekly Summary
        office:
          type: string
          description: USDA AMS office that published the report.
          example: National
        section_name:
          type: string
          description: Section name within the report.
          example: All Classes
    ErrorResponse:
      type: object
      title: Error Response
      description: Standard error response from the MARS API.
      properties:
        error:
          type: string
          description: Error type or code.
          example: invalid_parameter
        message:
          type: string
          description: Human-readable error message.
          example: The requested resource was not found.
        status:
          type: integer
          description: HTTP status code.
          example: 404
    ReportsListResponse:
      type: object
      title: Reports List Response
      description: Paginated list of market news reports.
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Report'
        stats:
          $ref: '#/components/schemas/PaginationStats'
    ReportDataResponse:
      type: object
      title: Report Data Response
      description: Response containing detailed report data.
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/ReportData'
        stats:
          $ref: '#/components/schemas/PaginationStats'
    PaginationStats:
      type: object
      title: Pagination Stats
      description: Pagination metadata for list responses.
      properties:
        count:
          type: integer
          description: Number of records in this response.
          example: 100
        total:
          type: integer
          description: Total number of records matching the query.
          example: 500
    ReportData:
      type: object
      title: Report Data
      description: Detailed commodity price and market data from a report.
      properties:
        slug_id:
          type: string
          description: Unique identifier for the report.
          example: '2451'
        slug_name:
          type: string
          description: Name of the report.
          example: National Weekly Cattle Summary
        report_date:
          type: string
          format: date
          description: Date the report data covers.
          example: '2026-04-18'
        published_date:
          type: string
          format: date-time
          description: Date the report was published.
          example: '2026-04-18T16:00:00Z'
        commodity:
          type: string
          description: Agricultural commodity.
          example: Cattle
        class:
          type: string
          description: Class or category within the commodity.
          example: Slaughter
        grade:
          type: string
          description: Grade or quality designation.
          example: Choice
        head_count:
          type: integer
          description: Number of head (animals) in the report.
          example: 45000
        price_per_cwt:
          type: number
          format: double
          description: Price per hundredweight (CWT).
          example: 185.5
        price_unit:
          type: string
          description: Unit of price measurement.
          example: CWT
        region:
          type: string
          description: Geographic region covered.
          example: National
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: API key obtained from USDA AMS MyMarketNews registration. Use the API key as the username with an empty password, or encode as Base64 for Bearer auth. Public access without authentication is also available with lower rate limits.