NAV Navbar
cURL NodeJS Python Go

Introduction

Welcome to the Zirra API! You can use our API to access information that Zirra has collected and created about companies.

This API is created using REST principles. Some operations allow you to be notified about new information or status changes - in these cases the API offers webhooks.

We currently have reference code in Shell; JavaScript, Python, and Go coming soon. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authorization

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: apiKey your-zirra-api-key"
//TODO: Coming soon.
//TODO: Coming soon.
//TODO: Coming soon.

Make sure to replace your-zirra-api-key with your real API key.

The Zirra API uses API keys to authorize requests. You can view and manage your API keys in your Account Settings.

The Zirra API expects for the API key to be included in all API requests to the server in a header as follows:

Authorization: apiKey your-zirra-api-key

Pagination

An example paginated response

{
    "elapsed": "98.784639ms",
    "totalCount": 5,
    "skip": 0,
    "dataCount": 1,
    "data" : [
        {
            "id": "microsoft",
            "name": "Microsoft",
            "website": "www.microsoft.com",
            "tickers": ["MSFT.NASDAQ", "MSFT.MX"],
            "description": "Microsoft, a software corporation that develops, manufactures, 
                licenses, supports, and sells a range of software products and services."
        }
    ]
}

All top-level API resources support pagination via the skip and limit parameters.

Argument Description
skip How many items in the result set to skip
limit How many items to return in the response

All these top-level API resources will return the results in a list contained in the data property, along with some additional metadata.

Parameter Data Type Description
elapsed string How long the request took to process.
totalCount number Total number of entities matching the request.
skip number The starting position of the result set in data.
dataCount number The number of entities in the data array.
data [object] The results.

Conventions

This section covers some conventions used by the Zirra API.

Datetimes

Examples of acceptable datetime arguments.

2019-05-19
20190519
2019-05-19T11:40:59Z
2019-05-19T11:40:59+05:00
2019-05-19T11:40

The Zirra API accepts and returns datetimes according to the ISO 8601 standard. Return values will always be a full UTC date and time. Arguments passed in are valid so long as at least a date is parsable.

Errors

Zirra API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
403 Forbidden -- Your key is recognized, but your request is not allowed under your plan.
404 Not Found -- The specified item could not be found.
429 Too Many Requests -- You're making too many requests in too short a time. Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Companies

Available Endpoints

    GET /v1/companies/

The Company object is the heart of the Zirra data universe. Fundamentally, every given data point Zirra collects will be tied to one (or more) companies. For timeseries data, the relationship is even stricter - a given data point is of a particular metric, and is always linked to exactly one company, at exactly one point in time.

As such, the endpoint for the Company allows for searching and identification of the companies of interest.

The Company Object

An example company object

{
    "id": "microsoft",
    "name": "Microsoft",
    "website": "www.microsoft.com",
    "tickers": ["NASDAQ:MSFT", "US:MSFT", "MSFT"],
    "description": "Microsoft, a software corporation that develops, manufactures, 
        licenses, supports, and sells a range of software products and services."
}
Parameter Data Type Description
id string Unique identifier for the object. Use this value in subsequent API calls to get data of interest about the company in question.
name string The name of the company.
website ISODate The main operating website of the company.
tickers [string] For public companies, an array of known tickers.
description string A short description about the company, to assist in identification.

Find Companies

An example of finding a company by ticker

curl "https://api.zirra.dev/v1/companies?ticker=MSFT"
  -H "Authorization: apiKey your-zirra-api-key"
//TODO: Coming soon.
//TODO: Coming soon.
//TODO: Coming soon.

Most of the parameters in the company object are available as arguments for search. All parameters are optional.

Argument Description
name Search by name. This is the most flexible way to search.
website Search by website. The search will prioritize the top level domain match over strict subdomain matching.
ticker Search by the company ticker.

Timeseries

Available Endpoints

    GET /v1/timeseries/

Zirra tracks, collects and generates data on companies over time. A Timeseries is a particular metric about Company entities tracked over time. For example, one timeseries might be daily number of times the given company mentioned in the news. Another might be the daily webtraffic the company gets at its main website.

Currently Zirra has defined over 100 timeseries that are continuously maintained and updated for thousands of companies.

The Timeseries Object

An example timeseries object

{
    "id": "CNT-NWSART-MNTN",
    "name": "News mentions - total",
    "description": "Number of times a company was mentioned in the news",
    "calculated": false,
    "frequency": "daily",
    "pricingPlans": [
        "basic",
        "pro",
        "ultra",
        "mega"
    ],
    "minValue": 0,
    "maxValue": 1000,
    "startTime": "2014-01-01T00:00:00Z",
    "isInteger": true,
    "delay": 7776000000000000
}
Parameter Data Type Description
id string Unique human readable identifier for the object. Use this value in subsequent API calls to get data of interest about the timeseries in question.
name string The name of the timeseries.
description string A short description about the timeseries.
calculated boolean Indicates whether the timeseries is calculated from other timeseries.
frequency string Indicates the native frequency (periodicity) of the timeseries.
pricingPlans [string] List of pricing plans that provide access to the given timeseries.
minValue number The minimum possible value for any observation in the given timeseries.
maxValue number The maximum possible value for any observation in the given timeseries.
startTime date The earliest allowed timestamp for the given timeseries.
isInteger boolean Indicates if the timeseries observation values are always integers.
delay number Indicates the time until data is available or is released. For example, a 10-Q filing can be filed up to 45 days after the end of fiscal quarter.

Timeseries IDs

Every timeseries has a unique id code assigned to it, and these codes are intended to be an ID that the API will accept, yet still be human readable. IDs are comprised of four parts in the following structure: AAA-BBBBBBCCC-DDDD

ID Part Data Type Description
AAA string Required. This prefix specifies the type of the timeseries. (See table below for types.)
BBBBBB string Required. A short descriptor of the timeseries. For example NWSART refers to timeseries data derived from news articles.
CCC integer Optional. Some timeseries are sourced, rather than generated/aggregated by Zirra. Sourced data will have this numerical counter in the code. For example AMT-WBTRFC1-ALL and AMT-WBTRFC2-ALL indicate two distinct sources of web traffic data.
DDDD string Optional. Additional descriptor for the timeseries.
ID Prefix Meaning
AMT An amount. For example, the number of shares transacted in some insider trade.
CNT A count. For example, the number of facebook likes.
INS An instance. For example, detection in the news of a particular company related event.
RTO A ratio. For example, the ratio of a funding raise to the total raised funds.
SCR A score obtained from a source, for which the scoring formula is external to Zirra. For example, employee reviews that generate a score about company diversity.
TIM A timespan. For example, the number of days since any event was seen.

Find Timeseries

An example of finding timeseries that are daily and related to events.

curl "https://api.zirra.dev/v1/timeseries?frequency=daily&description=news"
  -H "Authorization: apiKey your-zirra-api-key"
//TODO: Coming soon.
//TODO: Coming soon.
//TODO: Coming soon.

Most of the parameters in the timeseries object are available as arguments for search. All search parameters are optional.

Argument Matching logic
id Case insensitive partial (substring) matching.
name Case insensitive partial (substring) matching.
description Case insensitive partial (substring) matching.
calculated Exact boolean match.

Timeseries Data

Available Endpoints

    GET /v1/timeseries/:timeseries/:company

This endpoint allows for the retrieval and optional manipulation of the timeseries data available for a particular timeseries for a particular company.

In addition to the standard pagination parameters, the following optional parameters are available.

Parameter Data Type Values Description
startDate date Any ISO 8601 string. Returns data on and after the specified start date.
endDate date Any ISO 8601 string. Returns data on or before the specified end date.
order string asc, desc Specify the ordering of the returned data. Defaults to desc.
collapse string none, daily, weekly, monthly, quarterly, annual Change the sampling frequency of the matching data. Default is none.
aggregate string none, avg, sum, min, max, count, first, last Perform aggregations on the matching data. Default is none. Calculation options are described below.
transform string none, diff, rdiff, rdiff_from, cumul, normalize Perform basic calculations on the matching data. Default is none. Calculation options are described below.

Data Calculations

The collapse, aggregate and transform options can be used together to provide powerful data manipulation options. They are always applied in order - collapse first, then aggregate and finally transform.

Collapse

The collapse option can be thought of as bucketing the timeseries into timeslices. Used in isolation, it is a simple method of subsampling the timeseries. It becomes more powerful when used in combination with transform and aggregate.

Aggregate

An example of using collapse and aggregate to view total funding raised each year.

curl "https://api.zirra.dev/v1/timeseries/AMT-FUNDING/wix?limit=100 \
      &collapse=annual&aggregate=sum"
  -H "Authorization: apiKey your-zirra-api-key"
//TODO: Coming soon.
//TODO: Coming soon.
//TODO: Coming soon.

With the timeseries partitioned into time slices by the collapse function, one can then apply useful aggregations within each slice. If collapse=none then the aggregation will be applied across all data that matches the query.

Name Effect
none No effect
avg Average of all values in the timeslice.
sum Sum of all values in the timeslice.
min The minimum value across all values in the timeslice.
max The maximum value across all values in the timeslice.
count The number of values in the timeslice.
first The first value in the timeslice.
last The last value in the timeslice.

Transform

An example of using collapse, aggregate and transform to view total cumulative funding raised year by year.

curl "https://api.zirra.dev/v1/timeseries/AMT-FUNDING/wix?limit=100 \
      &collapse=annual&aggregate=sum&transform=cumul"
  -H "Authorization: apiKey your-zirra-api-key"
//TODO: Coming soon.
//TODO: Coming soon.
//TODO: Coming soon.
Name Effect Formula
none No effect z[t] = y[t]
diff Difference between each value and the preceeding value. z[t] = y[t] – y[t-1]
rdiff Percent difference between each value and the preceeding value. z[t] = (y[t] – y[t-1]) / y[t-1]
rdiff_from Latest value as % increment z[t] = (y[latest] – y[t]) / y[t]
cumul Cumulative sum z[t] = y[0] + y[1] + … + y[t]
normalize Scale series to start at 100 z[t] = y[t] ÷ y[0] * 100