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"

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

You must replace your-zirra-api-key with your personal 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

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.

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.

Find Companies

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.

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.

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.