Connect API
Overview
The Connect API allows you to integrate the functionality of CapitalCube into your own website or application. You can request or modify any data resource you would have access to in the application itself. The available resources are described in further detail in this reference document.
Our API follows the principles of REST. We leverage standard HTTP methods as well as built-in HTTP features like HTTP authentication. As a result, the API can be understood by any of the many off-the-shelf HTTP clients. Along with REST, our API uses JSON as a media type. This means that all API calls return a JSON object, even for errors.
We took care to have predictable and discoverable resource-oriented URLs. This API was designed to makes it very easy to write, test and maintain applications built on top of it.
URL Syntax
<http|s>://[<email>:<password>@]api.capitalcube.com/<resource>[/subresource...][?<parameters>]
Authentication
Authentication Methods
All API calls must be authenticated. We provide two authentication methods, HTTP Basic Auth and a signature method.
The HTTP Basic Auth is the simplest option. Since we support cross-origin resource sharing (CORS), this method allows you to securely interact with our API from a client-side web application. All requests made using this method are restricted to the permissions afforded to the normal user of the provided credentials. This option is recommended for light to normal usage.
The signature method is more complex but also much more powerful. Requests made using this method can be performed securely over simple HTTP. This method also allows you to make full use of the programatic capabilities of this API as permitted by your Developer account. This option is recommended for normal to heavy usage.
HTTP Basic Auth (HTTPS Only)
In order to authenticate using the HTTP Basic Auth method, you will either need to provide your username and password with every request or provide an Authorization header. These requests MUST be sent over HTTPS to ensure that your credentials remain secure.
Signature Method (HTTP & HTTPS)
In order to authenticate using the signature method, you will need your API Key and API Secret (both of which can be found in the account tab of the Connect Dashboard).
All signed requests to the Connect API must have the following parameters:
Parameters:
key: string
A 20 character alphanumeric string. You can find your API Key in the Connect Dashboard (under the Account section).
timestamp: string
The UNIX timestamp of the API request.
nonce: string
An 8 digit random number. The API Nonce is used to make the API Signature unique, even if the same request is made twice within a second.
signature: string
A SHA-1 digest of the key, timestamp, nonce, other url parameters and the user’s API Secret as the key.
API Signature Generation
Convert all text parameters to UTF-8 encoding.
| Parameter |
Value |
| exchange |
Euronext Paris |
| timestamp |
1382371516928 |
| nonce |
53260049 |
| key |
HvpSkWYX9K3mhCI3zD2v |
URL encode all text parameters.
| Parameter |
Value |
| exchange |
Euronext%20Paris |
| timestamp |
1382371516928 |
| nonce |
53260049 |
| key |
HvpSkWYX9K3mhCI3zD2v |
Sort parameter fields based on their encoded names (sort by lexicographical byte value ordering).
| Parameter |
Value |
| exchange |
Euronext%20Paris |
| key |
HvpSkWYX9K3mhCI3zD2v |
| nonce |
53260049 |
| timestamp |
1382371516928 |
Concatenate parameters into a single string. Fields should be separated from their corresponding value by an '=', while field-value pairs should be separated from one another by a '&' character.
exchange=Euronext%20Paris&key=HvpSkWYX9K3mhCI3zD2v&nonce=53260049&
timestamp=1382371516928
Concatenate the secret onto the end of your parameter string (step 4 above).
exchange=Euronext%20Paris&key=HvpSkWYX9K3mhCI3zD2v&nonce=53260049&
timestamp=1382371516928HvpSkWYX9K3mhCI3zD2v
Calculate a SHA-1 digest of the above sting.
a410d4d87938b90fee68a41259e13d0d30efef38
The resulting authenticated API call will look like this:
http://api.capitalcube.com/companies?exchange=Euronext%20Paris&key=HvpSkWYX9K3mhCI3zD2v&nonce=53260049×tamp=1382371516928HvpSkWYX9K3mhCI3zD2v&signature=a410d4d87938b90fee68a41259e13d0d30efef38
Errors
Whenever the API is unable to process a call, it will return an error. The Connect API also uses conventional HTTP response codes to indicate these errors.
Properties:
code: number
The HTTP status code of the response.
title: string
The error title. This is a short error description.
message: string
A detailed error message.
Errors:
API Key Missing
code: 400
title: API Key Missing
The API Key is missing.
API Nonce Missing
code: 400
title: API Nonce Missing
The API Nonce is missing.
API Nonce Invalid
code: 400
title: API Nonce Invalid
The API Nonce is invalid.
API Timestamp Missing
code: 400
title: API Timestamp Missing
The API Timestamp is missing.
API Timestamp Invalid
code: 400
title: API Timestamp Invalid
The API Timestamp is invalid.
API Timestamp Expired
code: 400
title: API Timestamp Expired
The API Timestamp is expired.
API Signature Missing
code: 400
title: API Signature Missing
The API Signature is missing.
API Signature Invalid
code: 400
title: API Signature Invalid
The API Signature is invalid.
Digest Invalid
code: 400
title: Digest Invalid
The Digest is invalid.
Parameter Missing
code: 400
title: Missing Parameter
A required parameter is missing.
Parameter Invalid
code: 400
title: Invalid Parameter
A provided parameter is invalid.
Parameter Empty
code: 400
title: Parameter Empty
A provided parameter is empty when it should not be.
API Key Invalid
code: 401
title: API Key Invalid
The provided API Key does not seem to exist.
Permission Denied
code: 403
title: Permission Denied
You aren't allowed to perform the action you've just attempted.
Not Found
code: 404
title: Not Found
We couldn't find what you're looking for. Make sure you didn't make a spelling mistake.
Not Supported
code: 405
title: Method or parameter not supported
We don't currently support the action you've attempted to perform. This may change in the future.
Internal Error
code: 500
title: Internal Error
Something went wrong on our side. Sorry. We're probably already working on the problem but please get in touch with us anyways.
Resources
Companies
The Companies list resource represents a set of 40,000 global companies. A Company instance resource represents a company, along with a set of Reports describing the company’s financial position.
GET /companies
Retrieve a list of all companies.
Parameters:
fields (optional): string
Specifies the result properties to be returned. Each property name should be separated by a comma. An empty filter returns all properties.
Default: " ".
limit (optional): string
Specifies the number of results to be returned.
Default: "100".
search (optional): string
Case-insensitive search in the properties of the list items. If the fields parameter is specified, the search is restricted to those enumerated properties.
skip (optional): string
Specifies the number of results to skip at the beginning of the result set.
Default: "0".
sort (optional): string
Specifies the property by which the returned results are sorted. Sorting over multiple properties can be achieved by separating the property names by a comma. Sorting is ascending by default. For a descending sort, prepend '-' to the property name.
Default: "name".
Filtering:
To filter the result set, provide the property name you want to filter on as a key and the desired match as a value. These filter parameters can be chained to create advanced queries. For instance, 'country=CANADA&exchange=TORONTO' would only return companies listed on the Toronto Stock Exchange in Canada.
Properties:
country: string
The country where the company is listed.
exchange: string
The stock exchange on which the company is listed.
name: string
The legal name of the company.
symbol: string
The ticker symbol and the country code of the company (eg. "AAPL-US").
isin: string
The International Securities Identification Number of the company (eg. "AAPL-US").
GET /companies/{{company}}
Retrieve a company's details.
Parameters:
Properties:
asOfDate: string
The date on which this company's information was last updated.
closingPrice: number
The price of the company's shares at close.
country: string
The country where the company is listed.
currency: string
The currency under which the company's number are provided in this resource.
exchange: string
The stock exchange on which the company is listed.
fiftyTwoWeekHigh: number
The maximum price of the company's shares over the past year.
fiftyTwoWeekLow: number
The minimum price of the company's shares over the past year.
filingCurrency: string
The currency under which the company's shares are listed.
industryGroup: string
The company's group based on its lines of business.
latestAnnualFilingDate: string
The date of the company's last annual filling. This value is "N/A" if the company has not published an annual filing.
latestSemiAnnualFilingDate: string
The date of the company's last semi-annual filling. This value is "N/A" if the company has not published a semi-annual filing.
latestQuarterlyAnnualFilingDate: string
The date of the company's last quarterly filling. This value is "N/A" if the company has not published a quarterly filing.
listedDate: string
The date on which the company's stock was listed.
marketCap: number
The company's market capitalization.
name: string
The legal name of the company.
nextReleaseDate: string
The date on which the company's next corporate fillings will be published.
oneMonthSharePricePerformance: number
The performance of the company's shares over the past month.
oneYearSharePricePerformance: number
The performance of the company's shares over the past year.
profile: string
The company's profile.
symbol: string
The ticker symbol and the country code of the company (eg. 'AAPL-US').
GET /companies/{{company}}/peers
Retrieve a company's peers.
Parameters:
Properties:
peerList: object
A list of the company objects representing this company's peers.
peerType: string
The peer type of the peer list returned. This value can either be aiPeers, if the peer set is ours, or custom, if the peer set is yours.
POST /companies/{{company}}/peers
Set the company's peers.
Body:
A JSON array of company symbols (string). The list of company provided will replace the existing peer set.
e.g. ["GOOG-US", "AAPL-US", "MSFT-US", "AMZN-US"]
PUT /companies/{{company}}/peers
Update the company's peers.
Body:
A JSON array of company symbols (strings). The list of company provided will be added to the existing peer set.
e.g. ["LLOY-GB", "RBS-GB", "BARC-GB", "RY-CA"]
DELETE /companies/{{company}}/peers
Reset the company's peers.
If the company has custom peers, they will be reset to aiPeers (the default peer set). If the company has not set custom peers, this action is idempotent.
GET /companies/{{company}}/peers/analysis
Retrieve the analysis reports of the company's peers.
Available Reports:
Corporate Actions
Dividend Quality
Earnings Quality
Fundamental Analysis
GET /companies/{{company}}/reports
Retrieve a list of reports for the company.
Properties:
name: object
The name of the report.
GET /companies/{{company}}/reports/{{report}}
Retrieve a specific report for the company.
Available Reports:
Corporate Actions
Competition
Dividend Quality
Earnings Quality
Earnings Release
Financials
Fundamental Analysis
Peer Characteristics
Price History
Snapshot
Trends
Exchange-traded funds (ETFs)
The ETFs list resource represents a set of popular American ETFs. An ETF instance resource represents an ETF, along with a set of Reports describing the exchange-traded fund’s financial position.
GET /etfs
Retrieve a list of all ETFs.
Parameters:
fields (optional): string
Specifies the result properties to be returned. Each property name should be separated by a comma. An empty filter returns all properties.
Default: " ".
limit (optional): string
Specifies the number of results to be returned.
Default: "100".
search (optional): string
Case-insensitive search in the properties of the list items. If the fields parameter is specified, the search is restricted to those enumerated properties.
offset (optional): string
Specifies the number of results to skip at the beginning of the result set.
Default: "0".
sort (optional): string
Specifies the property by which the returned results are sorted. Sorting over multiple properties can be achieved by separating the property names by a comma. Sorting is ascending by default. For a descending sort, prepend '-' to the property name.
Default: "name".
Filtering:
To filter the result set, provide the property name you want to filter on as a key and the desired match as a value. These filter parameters can be chained to create advanced queries. For instance, 'country=UNITED%20STATES&exchange=NASDAQ' would only return exchange-traded funds listed on the Nasdaq in the US.
Properties:
country: string
The country where the ETF is listed.
Only "United States" ETFs are available at the moment.
exchange: string
The stock exchange on which the ETF is listed.
name: string
The legal name of the ETF.
symbol: string
The ticker symbol and the country code of the ETF (eg. "MDY-US").
GET /etfs/{{etf}}
Retrieve an ETF's details.
Parameters:
Properties:
asOfDate: string
The date on which this ETF's information was last updated.
assetClass: string
The asset class of the ETF.
averageDailyVolume: number
The average daily trading volume of the ETF's shares.
closingPrice: number
The price of the ETF's shares at close.
country: string
The country where the ETF is listed.
currency: string
The currency under which the ETF's number are provided in this resource.
etfType: string
The ETF's type classification.
exchange: string
The stock exchange on which the ETF is listed.
inceptionDate: string
The date on which the fund was launched.
inceptionSharePricePerformance: number
The annualized performance of the ETF's shares since its inception.
fiftyTwoWeekHigh: number
The maximum price of the company's shares over the past year.
fiftyTwoWeekLow: number
The minimum price of the company's shares over the past year.
fundLegalStructure: string
The ETF's legal structure.
name: string
The legal name of the ETF.
netAssets: number
The ETF's net assets.
netAssetsAsOfDate: string
The date on which the ETF's net assets were last updated.
netExpenseRatio: number
The ETF's net expense ratio.
oneDaySharePricePerformance: number
The performance of the company's shares over the past day.
oneFiveYearSharePricePerformance: number
The annualized performance of the ETF's shares over the past 5 years.
oneMonthSharePricePerformance: number
The performance of the ETF's shares over the past month.
oneYearSharePricePerformance: number
The performance of the ETF's shares over the past year.
profile: string
The company's profile.
sponsor: string
The company that created and administers the exchange-traded fund.
symbol: string
The ticker symbol and the country code of the ETF (eg. 'MDY-US').
GET /etfs/{{etf}}/peers
Retrieve an ETF's peers.
Parameters:
Properties:
peerList: object
A list of the ETF objects representing this ETF's peers.
peerType: string
The peer type of the peer list returned. This value can either be aiPeers, if the peer set is ours, or custom, if the peer set is yours.
POST /etfs/{{etf}}/peers
Set the ETF's peers.
Body:
A JSON array of ETF symbols (string). The list of ETFs provided will replace the existing peer set.
e.g. ["SCHM-US", "VO-US", "IWR-US", "IJH-US"]
PUT /etfs/{{etf}}/peers
Update the ETF's peers.
Body:
A JSON array of ETF symbols (strings). The list of ETFs provided will be added to the existing peer set.
e.g. ["SCHM-US", "VO-US", "IWR-US", "IJH-US"]
DELETE /etfs/{{etf}}/peers
Reset the ETF's peers.
If the ETF has custom peers, they will be reset to aiPeers (the default peer set). If the ETF has not set custom peers, this action is idempotent.
GET /etfs/{{etf}}/peers/analysis
Retrieve the analysis reports of the ETF's peers.
Available Reports:
Corporate Actions
Dividend Quality
Earnings Quality
Fundamental Analysis
GET /etfs/{{etf}}/reports
Retrieve a list of reports for the ETF.
Properties:
name: object
The name of the report.
GET /etfs/{{etf}}/reports/{{report}}
Retrieve a specific report for the ETF.
Available Reports:
Analysis
Competition
Peer Characteristics
Price History
Trends