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

async fetch_iban_validation(iban)

This function is a coroutine.

Retrieves an IBANValidation.

Parameters:

iban (str) – The IBAN to retrieve from.

Raises:

HTTPException – Retrieving the IBAN validation failed.

Returns:

The retrieved IBAN validation.

Return type:

IBANValidation

async fetch_inflation(country, *, type=...)

This function is a coroutine.

Retrieves an Inflation with the specified country.

Parameters:
Raises:

HTTPException – Retrieving the inflation failed.

Returns:

The retrieved inflation.

Return type:

Inflation

async fetch_inflations(*, type=...)

This function is a coroutine.

Retrieves a list of available Inflation.

Parameters:

type (InflationIndicatorType) – The inflation indicator type.

Raises:

HTTPException – Retrieving the inflation failed.

Returns:

The retrieved list of available inflation.

Return type:

List[Inflation]

Utilities

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

apininjas.utils.MISSING

A type-safe sentinel used within the library to indicate a missing value, distinct from None.

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.

InflationIndicatorType

class apininjas.InflationIndicatorType

Specifies the type of inflation indicator.

cpi

The Consumer Price Index.

hicp

The Harmonized Index of Consumer Prices.

InflationCountry

class apininjas.InflationCountry

Specifies the inflation country.

austria

Austria.

belgium

Belgium.

brazil

Brazil.

canada

Canada.

chile

Chile.

china

China.

czech_republic

Czech Republic.

czechia

Alias of czech_republic.

denmark

Denmark.

estonia

Estonia.

finland

Finland.

france

France.

germany

Germany.

greece

Greece.

hungary

Hungary.

iceland

Iceland.

india

India.

indonesia

Indonesia.

ireland

Ireland.

israel

Israel.

italy

Italy.

japan

Japan.

mexico

Mexico.

norway

Norway.

poland

Poland.

portugal

Portugal.

russia

Russia.

slovakia

Slovakia.

slovenia

Slovenia.

south_korea

South Korea.

south_africa

South Africa.

spain

Spain.

sweden

Sweden.

switzerland

Switzerland.

netherlands

The Netherlands.

turkiye

Türkiye.

united_kingdom

United Kingdom.

uk

Alias of united_kingdom.

united_states

United States.

usa

Alias of united_states.

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.

str(x)

Returns the stock’s name.

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.

str(x)

Returns the name of the commodity future.

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.

str(x)

Returns the cryptocurrency’s symbol.

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.

str(x)

Returns the currency’s name.

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

IBANValidation

Attributes
Methods
class apininjas.IBANValidation

Represents an International Bank Account Number (IBAN) validation from the IBAN API.

str(x)

Returns the IBAN.

x == y

Checks if two IBANs are equal.

x != y

Checks if two IBANs are not equal.

iban

The IBAN.

Type:

str

bank_name

The bank’s name, which the IBAN belongs to.

Type:

str

account_number

The account number from the IBAN.

Type:

str

bank_code

The bank code from the IBAN.

Type:

str

country_code

The country code from the IBAN.

Type:

str

checksum

The checksum from the IBAN.

Type:

str

bban

The Basic Bank Account Number (BBAN) from the IBAN.

Type:

str

valid

Whether the IBAN is valid or not.

Note

This only includes the IBAN checksum validation.

Type:

bool

is_valid()

bool: Checks whether the IBAN is valid or not.

Note

This only includes the IBAN checksum validation.

Inflation

Attributes
Methods
class apininjas.Inflation

Represents the inflation of a country from the Inflation API.

x == y

Checks if two inflations are equal.

x != y

Checks if two inflations are not equal.

country

The country to which the inflation belongs.

Type:

str

type

The type of inflation indicator.

Type:

InflationIndicatorType

monthly_rate

The inflation rate on a monthly basis, in percent.

Type:

float

yearly_rate

The inflation rate on a yearly basis, in percent.

Type:

float

property period

The time period for the inflation data.

Type:

datetime.datetime

is_monthly_increased()

bool: Whether the monthly inflation rate increased.

is_yearly_increased()

bool: Whether the yearly inflation rate increased.

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