Shodan

Shodan Trends API

Trends is the historical analytics API for Shodan, exposing breakdowns of historical scan results aggregated by facet (product, port, country, organization, etc.) by month. Access is Enterprise-only.

GitHub OpenAPI

Documentation

📖
Documentation
https://developer.shodan.io/api/trends
📖
APIReference
https://developer.shodan.io/api/trends

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/shodan/refs/heads/main/openapi/shodan-trends-openapi.yml

Examples

📝
Example
https://raw.githubusercontent.com/api-evangelist/shodan/refs/heads/main/examples/shodan-trends-search-example.json

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/shodan/refs/heads/main/json-schema/shodan-trends-result-schema.json

OpenAPI Specification

shodan-trends-openapi.yml Raw ↑ 
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: [email protected]
    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' }