openapi: 3.0.3
info:
  title: S&P Global Commodity Insights Authentication Search API
  description: HTTP-based RESTful API providing access to energy and commodity market data through the S&P Global Commodity Insights (formerly Platts) platform. Covers market data, reference data, and historical prices for oil, gas, petrochemicals, power, shipping, metals, and agriculture. Supports JSON and XML response formats.
  version: 1.0.0
  contact:
    name: S&P Global Developer Portal
    url: https://developer.spglobal.com/
  termsOfService: https://www.spglobal.com/en/terms-of-use
servers:
- url: https://api.platts.com
  description: S&P Global Commodity Insights production API
- url: https://developer.platts.com
  description: S&P Global Commodity Insights developer portal API
tags:
- name: Search
  description: Entity search and discovery
paths:
  /search:
    get:
      operationId: searchEntities
      summary: Search Entities
      description: Search for entities by name, ticker symbol, or other attributes. Returns a ranked list of matching entity candidates with confidence scores.
      tags:
      - Search
      security:
      - BearerAuth: []
      parameters:
      - name: q
        in: query
        required: true
        description: Search query string (entity name, ticker, or other identifier)
        schema:
          type: string
          example: Apple Inc
      - name: entityType
        in: query
        required: false
        description: Filter results by entity type
        schema:
          type: string
          enum:
          - company
          - person
          - instrument
          - fund
          - index
          example: company
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
      responses:
        '200':
          description: Entity search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '401':
          description: Unauthorized
components:
  schemas:
    SearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/EntityCandidate'
        total:
          type: integer
          description: Total number of matching results
    EntityCandidate:
      type: object
      properties:
        keid:
          type: string
          description: Kensho Entity Identifier
          example: keid_abc12345
        name:
          type: string
          description: Canonical entity name
          example: Apple Inc.
        entityType:
          type: string
          description: Entity type classification
          example: company
        confidence:
          type: number
          format: double
          description: Confidence score for this candidate (0.0 to 1.0)
          minimum: 0
          maximum: 1
          example: 0.98
        crossReferences:
          $ref: '#/components/schemas/CrossReferences'
    CrossReferences:
      type: object
      description: Cross-references to identifiers in other systems
      properties:
        spglobalCompanyId:
          type: string
          description: S&P Global Company ID (Capital IQ)
          example: 0078552
        ticker:
          type: string
          description: Primary exchange ticker symbol
          example: AAPL
        cusip:
          type: string
          description: CUSIP identifier
          example: 037833100
        isin:
          type: string
          description: ISIN identifier
          example: US0378331005
        lei:
          type: string
          description: Legal Entity Identifier
          example: HWUPKR0MPOU8FGXBT394
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT