Finazon REST API introduction

The article describes the basic features of the Finazon API.

API reference

Finazon is a comprehensive financial data marketplace that enables publishers to place, and developers to integrate a wide variety of datasets, including stocks, ETFs, cryptocurrencies, and more, all with fully customizable parameters.

REST API

The Finazon API is built around REST principles, featuring resource-oriented URLs with predictable behavior. The API accepts form-encoded request bodies, returns JSON-encoded responses, and utilizes standard HTTP response codes, authentication methods, and verbs.

The Finazon API doesn't support bulk updates. You can work on only one instrument per request.

Authentification

To authenticate requests, the Finazon API requires API keys. You can obtain, view, and manage your API keys through the Finazon Dashboard.

Your API keys hold significant privileges, so ensure their security by not sharing your secret API keys in publicly accessible areas, such as GitHub repositories, client-side code, or any other public platforms.

All API requests must be made over HTTPS. Calls over plain HTTP will fail, as will API requests without authentication.

Once you have your API key, include it in the parameters as follows:

https://api.finazon.io/{...}?apikey={your_api_key}

Alternatively, pass the API key as a request header:

Authorization: apikey {your_api_key}

Versioning

Whenever backward-incompatible changes are introduced to the API, a new dated version is released. Consult our API upgrades guide for more information on backwards compatibility, and view our API changelog for all API updates.

To always use the most up-to-date version, specify it as /latest:

https://api.finazon.io/latest

To access the most recent version of v2.*, use the following:

https://api.finazon.io/v2

Or, to retrieve a specific version, call:

https://api.finazon.io/v2.0

Finazon will provide advance notice before deprecating older API versions, giving developers ample time to migrate to the updated version.

API v1.2 will be available until 01.01.2025. Read more.

Endpoints structure

The Finazon API adheres to a consistent and structured pattern for its endpoints:

https://api.finazon.io/{version}/{publisher_name}/{dataset_name}/{endpoint}?apikey={your_api_key}

Where:

• https://api.finazon.io/ — the base URL.
• {version} — API version, for example: latest.
• {publisher_name} — name of the publisher, for example: finazon.
• {dataset_name} — dataset code name, for example: sip_non_pro, forex.
• {endpoint} — endpoint of a particular dataset, for example: time_series, price, snapshots, tickers.

All endpoints are grouped by publishers and datasets, ensuring uniformity of requests and data within a specific publisher.

For instance, the US Equities Max time series can be requested as:

https://api.finazon.io/latest/sip/sip_non_pro/time_series?apikey={your_api_key}

Each dataset has its own documentation, for example: US Equities Max API docs.

We also strive for uniformity of requests and data across the entire service, facilitating rapid integration of new data into your applications.

Parameters

Each API request has its own set of required and optional parameters.

Parameters should be separated by an ampersand.

Parameter names and parameter values are case-sensitive.

For example:

https://api.finazon.io/latest/sip/sip_non_pro/time_series?ticker=AAPL&interval=1d&page=0&page_size=30&adjust=all&apikey={your_api_key}

Pagination

All API resources supporting bulk fetches are retrieved via "list" API methods. For example, you can list time series, trades, quotes. These list API methods share a common structure, accepting at least these five parameters:

• page,
• page_size,
• order,
• start_at,
• end_at.

The response of a list API method represents a single page in a reverse chronological stream of objects.

If you do not specify start_at or end_at, you will receive the first page of this list, containing the newest objects.

You can specify value for page_size. A default value can be seen in a dataset API docs.

You can specify start_at equal to the T (timestamp) value in UTC of an item to retrieve the page of older objects occurring immediately after the specified timestamp in the reverse chronological stream. Similarly, you can specify end_at to receive a page of newer objects occurring immediately before the named object in the stream. You can use one of start_at or end_at or both.

Objects in a page always appear in reverse chronological order, unless order is specified.

Errors

Finazon employs standard HTTP response codes to signify the success or failure of an API request. Generally, the response codes can be interpreted as follows:

• 2xx range codes indicate a successful request.
• 4xx range codes signify an error resulting from the provided information (e.g., invalid API key, API rate limit exceeded, etc.).
• 5xx range codes represent errors originating from Finazon's servers (these are rare occurrences).
• For all 4xx errors that can be addressed programmatically (e.g., endpoint not found), an error message is included to succinctly explain the reported issue. This allows developers to quickly identify and resolve errors in their API requests.

Error codes table: