API Reference

This section provides a detailed overview of the API of apininjas.py.

Clients

Client

Methods
class apininjas.Client(api_key)

Represents a client that interacts with the API.

async with x

Asynchronous context manager for the client that automatically cleans up.

Parameters:

api_key (str) – The API key to authenticate.

is_closed()

bool: Whether the client is closed or not.

async close()

Closes the client.

This closes all connections to the API.

async fetch_stock(ticker)

This function is a coroutine.

Retrieves a Stock with the specified ticker.

Parameters:

ticker (str) – The ticker to fetch from.

Raises:
Returns:

The retrieved stock.

Return type:

Stock

async fetch_commodity(type)

This function is a coroutine.

Retrieves a Commodity with the specified type.

Parameters:

type (CommodityType) – The type of the commodity to fetch from.

Raises:

HTTPException – Retrieving the commodity failed.

Returns:

The retrieved commodity.

Return type:

Commodity

async fetch_crypto(symbol)

This function is a coroutine.

Retrieves a Crypto with the specified symbol.

Parameters:

symbol (str) – The symbol to fetch from.

Raises:

HTTPException – Retrieving the cryptocurrency failed.

Returns:

The retrieved cryptocurrency.

Return type:

Crypto

async fetch_crypto_symbols()

This function is a coroutine.

Retrieves a list of all available cryptocurrency symbols.

Raises:

HTTPException – Retrieving the symbols failed.

Returns:

The retrieved list of available symbols.

Return type:

List[str]

async fetch_currency_conversion(*, have, have_amount, want)

This function is a coroutine.

Retrieves a converted CurrencyWithAmount from the specified have currency and have_amount and returns the old and new one.

Parameters:

  • have (str) – The currency name to convert from (e.g. AUD).

  • have_amount (float) – The amount of the have currency to convert from.

  • want (str) – The currency name to convert to (e.g. GBP).

Raises:

HTTPException – Retrieving the currency failed.

Returns:

The old and newly retrieved currency with their respective amounts.

Return type:

Tuple[CurrencyWithAmount, CurrencyWithAmount]

async fetch_currency(name, *, reference)

This function is a coroutine.

Retrieves a Currency with the specified name and reference.

Parameters:

  • name (str) – The currency name to retrieve from (e.g. GBP).

  • reference (str) – The currency reference for the equivalent value (e.g. AUD).

Raises:

HTTPException – Retrieving the currency failed.

Returns:

The retrieved currency.

Return type:

Currency

Utility Functions

apininjas.utils.from_timestamp(timestamp, /)

A helper function that converts a given timestamp into a datetime object.

Parameters:

timestamp (int) – The timestamp to convert.

Returns:

The datetime object from the given timestamp.

Return type:

datetime.datetime

Enumerations

All enumerations inherit from enum.Enum.

CommodityType

class apininjas.CommodityType

Specifies the type of a commodity future.

gold

Gold Futures.

soybean_oil

Soybean Oil Futures.

wheat

Wheat Futures.

platinum

Platinum Futures.

micro_silver

Micro Silver Futures.

lean_hogs

Lean Hogs Futures.

corn

Corn Futures.

oat

Oat Futures.

aluminum

Aluminum Futures.

soybean_meal

Soybean Meal Futures.

silver

Silver Futures.

soybean

Soybean Futures.

lumber

Lumber Futures.

live_cattle

Live Cattle Futures.

sugar

Sugar Futures.

natural_gas

Natural Gas Futures.

crude_oil

Crude Oil Futures.

orange_juice

Orange Juice Futures.

coffee

Coffee Futures.

cotton

Cotton Futures.

copper

Copper Futures.

micro_gold

Micro Gold Futures.

feeder_cattle

Feeder Cattle Futures.

rough_rice

Rough Rice Futures.

palladium

Palladium Futures.

cocoa

Cocoa Futures.

brent_crude_oil

Brent Crude Oil Futures.

gasoline_rbob

Gasoline RBOB Futures.

heating_oil

Heating Oil Futures.

class_3_milk

Class III Milk Futures.

Abstract Base Classes

FinancialInstrument

Attributes
Methods
class apininjas.abc.FinancialInstrument

An ABC representing the common operations of a financial instrument.

Following classes inherit from this ABC:

price

The current price of the instrument, last updated at updated_at.

Type:

float

property updated_at

Date and time the price was last updated.

Type:

datetime.datetime

async update()

This function is a coroutine.

Updates price and updated_at of the current object and returns the new price.

Note

This makes an API call.

Raises:

HTTPException – Retrieving the price failed.

Returns:

The newly updated price.

Return type:

float

Models

Stock

Attributes
Methods
class apininjas.Stock

Represents a stock from the Stock Price API.

x == y

Checks if two stocks are equal.

x != y

Checks if two stocks are not equal.

x < y

Checks if a stock’s price is less than another.

x > y

Checks if a stock’s price is greater than another.

x <= y

Checks if a stock’s price is less or equal than another.

x >= y

Checks if a stock’s price is greater or equal than another.

ticker

The stock’s ticker symbol.

Type:

str

name

The stock’s name.

Type:

str

exchange

The stock exchange the stock is traded on. None if it’s not an exchange for stocks.

Type:

Optional[str]

price

The current price of the stock, last updated at updated_at.

Type:

float

async update()

This function is a coroutine.

Updates price and updated_at of the current object and returns the new price.

Note

This makes an API call.

Raises:

HTTPException – Retrieving the price failed.

Returns:

The newly updated price.

Return type:

float

property updated_at

Date and time the price was last updated.

Type:

datetime.datetime

Commodity

Attributes
Methods
class apininjas.Commodity

Represents a commodity future from the Commodity Price API or the Gold Price API.

x == y

Checks if two commodity futures are equal.

x != y

Checks if two commodity futures are not equal.

x < y

Checks if the price of a commodity future is less than the one of another.

x > y

Checks if the price of a commodity future is greater than the one of another.

x <= y

Checks if the price of a commodity future is less or equal than the one of another.

x >= y

Checks if the price of a commodity future is greater or equal than the one of another.

name

The name of the commodity future.

Type:

str

exchange

The exchange the commodity future is traded on.

Type:

str

price

The current price of the commodity future, last updated at updated_at.

Type:

float

type

The type of the commodity future.

Type:

CommodityType

async update()

This function is a coroutine.

Updates price and updated_at of the current object and returns the new price.

Note

This makes an API call.

Raises:

HTTPException – Retrieving the price failed.

Returns:

The newly updated price.

Return type:

float

property updated_at

Date and time the price was last updated.

Type:

datetime.datetime

Crypto

Attributes
Methods
class apininjas.Crypto

Represents a cryptocurrency from the Crypto Price API.

x == y

Checks if two cryptocurrencies are equal.

x != y

Checks if two cryptocurrencies are not equal.

x < y

Checks if a cryptocurrency’s price is less than another.

x > y

Checks if a cryptocurrency’s price is greater than another.

x <= y

Checks if a cryptocurrency’s price is less or equal than another.

x >= y

Checks if a cryptocurrency’s price is greater or equal than another.

symbol

The cryptocurrency’s symbol.

Type:

str

price

The current price of the cryptocurrency, last updated at updated_at.

Type:

float

async update()

This function is a coroutine.

Updates price and updated_at of the current object and returns the new price.

Note

This makes an API call.

Raises:

HTTPException – Retrieving the price failed.

Returns:

The newly updated price.

Return type:

float

property updated_at

Date and time the price was last updated.

Type:

datetime.datetime

Currency

Attributes
Methods
class apininjas.Currency

Represents a currency from the Exchange Rate API or Currency Conversion API.

x == y

Checks if two currencies are equal.

x != y

Checks if two currencies are not equal.

name

The name of the currency.

Type:

str

exchange_rate

The exchange rate relative to the reference currency.

Type:

float

reference

The name of the reference currency.

Type:
class:

str

is_stronger()

bool: Whether the currency is stronger (more valuable) than its reference.

async update()

This function is a coroutine.

Updates exchange_rate of the current object and returns the new exchange rate.

Note

This makes an API call.

Raises:

HTTPException – Retrieving the exchange rate failed.

Returns:

The newly updated exchange rate.

Return type:

float

class apininjas.CurrencyWithAmount

A namedtuple which represents a currency with an amount.

currency

The currency.

Type:

Currency

amount

The amount.

Type:

float

Exceptions

exception apininjas.APINinjasBaseException

Base exception class.

Every exception in this library is derived from this class.

exception apininjas.ClientException

Exception that’s raised when an operation in the Client fails.

This exception is often raised due to invalid user input.

exception apininjas.HTTPException(response, data)

HTTP Exception that’s raised when an HTTP request fails.

response

The response of the HTTP request.

Type:

aiohttp.ClientResponse

status

The HTTP status code.

Type:

int

reason

The HTTP reason-phrase if any.

Type:

Optional[str]

message

The related message sent by the API.

Type:

str

exception apininjas.NotFound(response, data)

HTTP Exception with status code 404.

Derives from HTTPException.

exception apininjas.MethodNotAllowed(response, data)

HTTP Exception with status code 405.

Derives from HTTPException.

exception apininjas.APINinjasServerError(response, data)

HTTP Exception with status code above 500.

Derives from HTTPException.

exception apininjas.StockNotFound

Exception that’s raised when a requested stock could not be found.

This exception is raised when the data returned by the API is invalid due to invalid user input.

Derives from ClientException.

Exception Hierarchy