api-ninjas-com Oil Price API

openapi: 3.2.0
info:
  title: Ninjas Oil Price API
  description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
  version: 1.0.0
  contact:
    name: API Ninjas
    url: https://api-ninjas.com
  license:
    name: Proprietary
servers:
- url: https://api.api-ninjas.com
  description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: Oil Price
  description: 'The Oil Price API provides real-time and historical prices for the major crude oil and energy benchmarks: WTI crude oil, Brent crude oil, natural gas, heating oil, and RBOB gasoline. Prices are returned in clean JSON with optional currency and unit conversion. The free tier returns the daily closing price for WTI and Brent; premium plans unlock real-time prices, all benchmarks, conversion, and historical OHLCV data.'
paths:
  /v1/oilprice:
    get:
      summary: Get the current oil / energy benchmark price
      operationId: getCurrentOilPrice
      description: Returns the current price for a crude oil or energy benchmark. Free tier returns the daily closing price for WTI (type=wti) and Brent (type=brent); premium tiers return the real-time price for all benchmarks and support optional currency and unit conversion.
      parameters:
      - name: type
        in: query
        required: false
        description: The oil/energy benchmark to return. Defaults to wti. crude_oil, brent_crude_oil, gasoline_rbob, and heating_oil are also accepted as aliases.
        schema:
          type: string
          enum:
          - wti
          - brent
          - natural_gas
          - gasoline
          - diesel
          default: wti
      - name: types
        in: query
        required: false
        description: Comma-separated list of benchmarks for a batch request. Available to Business, Professional, and Enterprise subscribers, or any annual plan.
        schema:
          type: string
          example: wti,brent,natural_gas
      - name: currency
        in: query
        required: false
        description: ISO 4217 currency code to convert the price into (e.g., EUR, GBP, INR). Premium feature.
        schema:
          type: string
          example: EUR
      - name: unit
        in: query
        required: false
        description: 'Target unit to convert the price into. Must match the benchmark''s dimension: crude oil, gasoline, and diesel (volume) accept barrel, gallon, liter, or cubic_meter; natural_gas (energy) accepts MMBtu, MWh, GJ, or therm. Premium feature.'
        schema:
          type: string
          enum:
          - barrel
          - gallon
          - liter
          - cubic_meter
          - MMBtu
          - MWh
          - GJ
          - therm
      responses:
        '200':
          description: Successful response. Object when called with type; array when called with types.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/OilPriceResponse'
                - type: array
                  items:
                    oneOf:
                    - $ref: '#/components/schemas/OilPriceResponse'
                    - $ref: '#/components/schemas/OilPriceOpenapi_BatchItemError'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      tags:
      - Oil Price
  /v1/oilspot:
    get:
      summary: Get the official daily spot price for an oil / energy benchmark
      operationId: getOilSpotPrice
      description: Premium only. Returns the daily spot price at the benchmark's physical delivery hub. Prices are published with a delay, so the date field says which trading day the price is for. The types batch parameter is available to Business, Professional, and Enterprise subscribers, or any annual plan.
      parameters:
      - name: type
        in: query
        required: false
        description: The benchmark to return. Defaults to wti. crude_oil, brent_crude_oil, gasoline_rbob, and heating_oil are also accepted as aliases.
        schema:
          type: string
          enum:
          - wti
          - brent
          - natural_gas
          - gasoline
          - diesel
          default: wti
      - name: types
        in: query
        required: false
        description: Comma-separated list of benchmarks for a batch request. Available to Business, Professional, and Enterprise subscribers, or any annual plan.
        schema:
          type: string
          example: wti,brent,natural_gas
      - name: currency
        in: query
        required: false
        description: ISO 4217 currency code to convert the price into (e.g., EUR, GBP, INR).
        schema:
          type: string
          example: EUR
      - name: unit
        in: query
        required: false
        description: 'Target unit to convert the price into. Must match the benchmark''s dimension: crude oil, gasoline, and diesel (volume) accept barrel, gallon, liter, or cubic_meter; natural_gas (energy) accepts MMBtu, MWh, GJ, or therm.'
        schema:
          type: string
          enum:
          - barrel
          - gallon
          - liter
          - cubic_meter
          - MMBtu
          - MWh
          - GJ
          - therm
      responses:
        '200':
          description: Successful response. Object when called with type; array when called with types.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/OilSpotResponse'
                - type: array
                  items:
                    oneOf:
                    - $ref: '#/components/schemas/OilSpotResponse'
                    - $ref: '#/components/schemas/OilPriceOpenapi_BatchItemError'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      tags:
      - Oil Price
  /v1/oilpricehistorical:
    get:
      summary: Get historical oil / energy benchmark prices
      operationId: getHistoricalOilPrice
      description: Returns historical OHLCV (Open, High, Low, Close, Volume) data for an oil/energy benchmark, most recent first. Reserved for premium subscribers.
      parameters:
      - name: type
        in: query
        required: false
        description: The oil/energy benchmark. Defaults to wti. crude_oil, brent_crude_oil, gasoline_rbob, and heating_oil are also accepted as aliases.
        schema:
          type: string
          enum:
          - wti
          - brent
          - natural_gas
          - gasoline
          - diesel
          default: wti
      - name: period
        in: query
        required: false
        description: Time interval between data points.
        schema:
          type: string
          enum:
          - 1m
          - 5m
          - 15m
          - 30m
          - 1h
          - 4h
          - 1d
          default: 1h
      - name: start
        in: query
        required: false
        description: Start timestamp in Unix format.
        schema:
          type: integer
      - name: end
        in: query
        required: false
        description: End timestamp in Unix format.
        schema:
          type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricalOilPriceResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - Reserved for premium subscribers.
        '500':
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      tags:
      - Oil Price
components:
  schemas:
    OilSpotResponse:
      type: object
      properties:
        type:
          type: string
          description: The requested benchmark (wti, brent, natural_gas, gasoline, or diesel).
        name:
          type: string
          description: The display name of the benchmark.
        price:
          type: number
          description: The daily spot price at the benchmark's physical delivery hub, as of date.
        spot_type:
          type: string
          enum:
          - assessed
          description: assessed = the daily spot price at the benchmark's delivery hub.
        date:
          type: string
          description: The trading day the price is for (YYYY-MM-DD). Daily spot prices are published with a delay, so it trails by several days.
        benchmark:
          type: string
          description: 'The physical spot benchmark: WTI Cushing, Oklahoma; Brent Europe; Henry Hub; New York Harbor conventional regular gasoline; or New York Harbor ultra-low sulfur diesel.'
        previous_close:
          type: number
          description: The spot price on the previous trading day.
        change_24h:
          type: number
          description: Change versus the previous close.
        change_24h_percent:
          type: number
          description: Percent change versus the previous close.
        updated:
          type: integer
          description: Unix timestamp (seconds) of the spot price.
        unit:
          type: string
          description: The quote unit.
        currency_unit:
          type: string
          description: Price currency, USD by default.
    OilPriceResponse:
      type: object
      properties:
        type:
          type: string
          description: The requested oil/energy benchmark (wti, brent, natural_gas, gasoline, or diesel).
        name:
          type: string
          description: The display name of the benchmark (e.g., Crude Oil, Brent Crude Oil).
        price:
          type: number
          description: The current price. Free tier returns the most recent daily closing price for WTI and Brent; premium tiers return the real-time price. See unit and currency_unit for the price convention.
        unit:
          type: string
          description: The quote unit (barrel for crude, gallon for heating oil / RBOB gasoline, MMBtu for natural gas). Can be converted with the unit parameter (premium).
        currency_unit:
          type: string
          description: Price convention, USD by default. Can be converted with the currency parameter (premium).
        previous_close:
          type: number
          description: The previous session's closing price.
        change_24h:
          type: number
          description: Change versus the previous close.
        change_24h_percent:
          type: number
          description: Percent change versus the previous close.
        high_24h:
          type: number
          description: The day's high price (real-time / premium).
        low_24h:
          type: number
          description: The day's low price (real-time / premium).
        high_52w:
          type: number
          description: 52-week high. Developer tier and above; returned as a premium-only message for free users.
        low_52w:
          type: number
          description: 52-week low. Developer tier and above; returned as a premium-only message for free users.
        updated:
          type: integer
          description: Unix timestamp (seconds) of the price.
        futures_contract:
          type: string
          description: The futures contract `price` is quoted for (e.g., GCZ26 = December 2026 gold).
        futures_contract_month:
          type: string
          description: Delivery month of futures_contract (YYYY-MM).
    OilPriceOpenapi_BatchItemError:
      type: object
      description: Error entry returned for a single type in a batch request that failed or is not permitted.
      properties:
        type:
          type: string
        error:
          type: string
    HistoricalOilPriceResponse:
      type: array
      items:
        type: object
        properties:
          open:
            type: number
            description: The opening price for this time period.
          low:
            type: number
            description: The lowest price during this time period.
          high:
            type: number
            description: The highest price during this time period.
          close:
            type: number
            description: The closing price for this time period.
          volume:
            type: integer
            description: The trading volume during this time period.
          time:
            type: integer
            description: The Unix timestamp (seconds) for this data point.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api