openapi: 3.1.0
info:
  title: Shodan Trends API
  description: >-
    The Shodan Trends API provides historical analytics on top of the
    complete Shodan scan dataset. Queries return monthly counts and faceted
    breakdowns over time. Enterprise plan required.
  version: '1.0'
  contact:
    name: Shodan Support
    email: support@shodan.io
    url: https://developer.shodan.io/api/trends
  license:
    name: Shodan API Terms of Service
    url: https://www.shodan.io/legal/tos
servers:
  - url: https://trends.shodan.io
    description: Production
security:
  - apiKey: []
tags:
  - name: Trends
paths:
  /api/v1/search:
    get:
      tags: [Trends]
      summary: Search Historical Trends
      operationId: searchTrends
      description: Return monthly counts and faceted aggregations for a historical Shodan search.
      parameters:
        - name: query
          in: query
          required: true
          schema: { type: string }
          description: Historical Shodan search query (e.g. `product:nginx`).
        - name: facets
          in: query
          schema: { type: string }
          description: Comma-separated facets with optional size suffix (e.g. `country:10`).
      responses:
        '200':
          description: Monthly counts and facet breakdowns.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TrendsResult' }
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: key
  schemas:
    MonthlyCount:
      type: object
      properties:
        month: { type: string, description: 'YYYY-MM' }
        count: { type: integer }
    FacetBucket:
      type: object
      properties:
        value: { type: string }
        count: { type: integer }
        matches:
          type: array
          items: { $ref: '#/components/schemas/MonthlyCount' }
    TrendsResult:
      type: object
      properties:
        total: { type: integer }
        matches:
          type: array
          items: { $ref: '#/components/schemas/MonthlyCount' }
        facets:
          type: object
          additionalProperties:
            type: array
            items: { $ref: '#/components/schemas/FacetBucket' }