All operations to the Graviton API must be authenticated using an API key. You get an API key when subscribing to the Graviton service. You can always retrieve your API key by signing in to the dashboard.

API Key
You must specify your API key in the headers of HTTP requests using the x-api-key header name. The following shows an example using curl.

curl -H "x-api-key: <api-key>" https://api.graviton.lu/v1/tickers
Replace <api-key> with your API key.

Alternatively, you may also use a query string parameter instead.

curl https://api.graviton.lu/v1/tickers?x-api-key=<api-key>
Replace <api-key> with your API key.

Security considerations
Your API key is like a password and must be kept secret. Do not share it with other parties and store it with care.

Rate limiting
The API is rate limited. If you hit your limit, the API reponds with an HTTP status code 429. In that case, you need to back off and retry later.

We recommend you to implement an exponential backoff algorithm for better flow control. The idea behind exponential backoff is to use progressively longer waits between retries for consecutive error responses. You should implement a maximum delay interval, as well as a maximum number of retries. The maximum delay interval and maximum number of retries are not necessarily fixed values, and should be set based on the operation being performed, as well as other local factors, such as network latency.

Errors
The following table lists potential errors returned by the API.

HTTP Status Code Name What to do
400 Bad Request Your request is malformed and you need to fix it. Check the error message returned in the response's body for additional information on the error.
401 Unauthorized Check that your API key is not missing or misspelled. Check that the URL specified is correct.
403 Access Denied Check that your API key is not missing or misspelled. Check that the URL specified is correct.
404 Not Found The resource you are trying to access doesn't exist.
405 Method Not Allowed Check the HTTP method (GET, POST, PUT...) used is the correct one.
406 Not Acceptable Check the Accept header of your request and try with this value /.
429 Too Many Requests You have hit the rate limit. Backoff and retry later.
5xx Server Errors Something went wrong on our side. You may retry later. If the problem persists, please contact us.
Some errors may return a message in the response's body. The format is as shown herefater.

{
"message": "Ticker specified not found."
}
If you still experience issues, feel free to contact us. We'll be happy to help.

Pagination
Some responses given by the API are paginated. Typically, this is the case for requests that return a list of items as response. With pagination, you will not get all items in a single response, but only a portion of all items. You need to execute other requests to retrieve subsequent pages.

Paginated reponse always have the same format, as shown below.

{
"page": [
{
...
},
{
...
}
],
"pageSize": 2,
"nextPage": "AHDsdisjdqi87SDDniidqsdi9890"
}
Property Description
page Contains the list of items returned by the API.
pageSize The number of items in the page.
nextPage The identifier that you can pass to the request to return the next page.
To return the next page, simply pass the value of the nextPage property to your request as a query string parameter named page.

curl -H "x-api-key: <api-key>" https://api.graviton.lu/v1/tickers?page=AHDsdisjdqi87SDDniidqsdi9890
You may specify the size of the page by specifiying the limit query string parameter. The following example will return a maximum of 200 items in a page.

curl -H "x-api-key: <api-key>" https://api.graviton.lu/v1/tickers?page=AHDsdisjdqi87SDDniidqsdi9890&limit=200
Cross-Origin Resource Sharing
Cross-Origin Resource Sharing (CORS) is a feature of modern web browsers that allows a website access to resources from another domain under certain conditions.

CORS is enabled on the graviton API so that you can request the API from browser-like clients for particular use cases.

The Graviton API requires consumers to be authenticated using an API key. Requesting the Graviton API from your frontend application running on the client's browser would expose your API key. This is discouraged.

Should you have the need to serve Graviton data to end users through a web application, we recommend implementing requests to the Graviton API server-side. Not only is this preventing disclosure of your API key, but allows better control of your rate limit against the Graviton API.

Tickers
Operations on tickers

List and search tickers
AUTHORIZATIONS:
API-Key
QUERY PARAMETERS
search
string
Search by ticker symbol, name, company name, ISIN, CUSIP or CIK

limit
number
The maximum number of returned tickers.
Default: 100
Min: 1
Max: 1000

page
string
The identifier of the page to return.

Responses
200 200 response
RESPONSE SCHEMA: application/json
Array ()
page
Array of objects (Ticker)
The tickers returned for the specified request.

pageSize
number
The number of tickers in the current page, returned for the specified request.

nextPage
string
The identifier of the next page of results.

GET
/tickers
Response samples
200
Content type
application/json

Copy
Expand allCollapse all
[
{
"page": [
{
"symbol": "AAPL",
"name": "Apple Inc",
"companyName": "Apple Inc",
"description": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables, and accessories worldwide. It also sells various related services. The company offers iPhone, a line of smartphones; Mac, a line of personal computers; iPad, a line of multi-purpose tablets; and wearables, home, and accessories comprising AirPods, Apple TV, Apple Watch, Beats products, HomePod, iPod touch, and other Apple-branded and third-party accessories. It also provides AppleCare support services; cloud services store services; and operates various platforms, including the App Store, that allow customers to discover and download applications and digital content, such as books, music, video, games, and podcasts. In addition, the company offers various services, such as Apple Arcade, a game subscription service; Apple Music, which offers users a curated listening experience with on-demand radio stations; Apple News+, a subscription news and magazine service; Apple TV+, which offers exclusive original content; Apple Card, a co-branded credit card; and Apple Pay, a cashless payment service, as well as licenses its intellectual property. The company serves consumers, and small and mid-sized businesses; and the education, enterprise, and government markets. It sells and delivers third-party applications for its products through the App Store. The company also sells its products through its retail and online stores, and direct sales force; and third-party cellular network carriers, wholesalers, retailers, and resellers. Apple Inc. was founded in 1977 and is headquartered in Cupertino, California.",
"exchangeName": "NASDAQ Global Select Market",
"exchangeMic": "XNGS",
"exchangeOperatingMic": "XNAS",
"etf": false,
"currency": "USD",
"cik": "0000320193",
"isin": "US0378331005",
"cusip": "037833100",
"industry": "Consumer Electronics",
"sector": "Technology",
"fullTimeEmployees": 147000,
"phone": 14089961010,
"address": "1 Apple Park Way",
"city": "Cupertino",
"state": "CALIFORNIA",
"zip": 95014,
"country": "US",
"website": "https://www.apple.com/",
"ipodate": "1980-12-12"
}
],
"pageSize": 100,
"nextPage": "AHDsdisjdqi87SDDniidqsdi9890"
}
]
Get a specific ticker
AUTHORIZATIONS:
API-Key
PATH PARAMETERS
symbol
required
string
The symbol of the ticker to return

Responses
200 200 response
RESPONSE SCHEMA: application/json
symbol
string
The ticker's symbol.

name
string
The name of the ticker.

companyName
string
The name of the company.

description
string
The description of the company.

exchangeName
string
The name of the exchange that this ticker is traded on.

exchangeMic
string
The Market Identifier Code (MIC) of the exchange that this ticker is traded on. The MIC is based on ISO 10383 that specifies a universal method of identifying exchanges.

exchangeOperatingMic
string
The operating Market Identifier Code (MIC) of the exchange that this ticker is traded on. The MIC is based on ISO 10383 that specifies a universal method of identifying exchanges.

etf
boolean
Whether this ticker is an Exchange Traded Fund (ETF) or not.

currency
string
The currency of the ticker.

cik
string
The Central Index Key (CIK) is used on the SEC's computer systems to identify corporations and individual people who have filed disclosure with the SEC.

isin
string
An International Securities Identification Number (ISIN) is a code that uniquely identifies a specific securities issue. The organization that allocates ISINs in any particular country is the country's respective National Numbering Agency (NNA).

cusip
string
A CUSIP is a nine-digit numeric or nine-character alphanumeric code that identifies a North American financial security for the purposes of facilitating clearing and settlement of trades.

industry
string
The industry classification that the company operates under.

sector
string
The sector classification that the company operates under.

fullTimeEmployees
integer
The number of full-time employees.

phone
string
The phone number of the company.

address
string
The address of the company.

city
string
The city part of the address of the company.

state
string
The state part of the address of the company.

zip
string
The zip part of the address of the company.

country
string
The country of the company.

website
string
The URL to the main website of the company.

ipodate
string
The IPO date of the company.

GET
/tickers/{symbol}
Response samples
200
Content type
application/json

Copy
Expand allCollapse all
{
"symbol": "AAPL",
"name": "Apple Inc",
"companyName": "Apple Inc",
"description": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables, and accessories worldwide. It also sells various related services. The company offers iPhone, a line of smartphones; Mac, a line of personal computers; iPad, a line of multi-purpose tablets; and wearables, home, and accessories comprising AirPods, Apple TV, Apple Watch, Beats products, HomePod, iPod touch, and other Apple-branded and third-party accessories. It also provides AppleCare support services; cloud services store services; and operates various platforms, including the App Store, that allow customers to discover and download applications and digital content, such as books, music, video, games, and podcasts. In addition, the company offers various services, such as Apple Arcade, a game subscription service; Apple Music, which offers users a curated listening experience with on-demand radio stations; Apple News+, a subscription news and magazine service; Apple TV+, which offers exclusive original content; Apple Card, a co-branded credit card; and Apple Pay, a cashless payment service, as well as licenses its intellectual property. The company serves consumers, and small and mid-sized businesses; and the education, enterprise, and government markets. It sells and delivers third-party applications for its products through the App Store. The company also sells its products through its retail and online stores, and direct sales force; and third-party cellular network carriers, wholesalers, retailers, and resellers. Apple Inc. was founded in 1977 and is headquartered in Cupertino, California.",
"exchangeName": "NASDAQ Global Select Market",
"exchangeMic": "XNGS",
"exchangeOperatingMic": "XNAS",
"etf": false,
"currency": "USD",
"cik": "0000320193",
"isin": "US0378331005",
"cusip": "037833100",
"industry": "Consumer Electronics",
"sector": "Technology",
"fullTimeEmployees": 147000,
"phone": 14089961010,
"address": "1 Apple Park Way",
"city": "Cupertino",
"state": "CALIFORNIA",
"zip": 95014,
"country": "US",
"website": "https://www.apple.com/",
"ipodate": "1980-12-12"