Introduction

Welcome to the NorthGravity API! You can use our API to upload, download, and search, or list files. All files may be uploaded together with metadata. Metadata are validated against the chosen file group.

Authentication

NG API allows both basic auth and bearer tokens to be used to access the API. NG API expects one type of authentication to be included in all API requests. For brevity, we will leave the authentication method out of the examples.

To authenticate, use Bearer Token or Basic Authentication:

curl "https://api.obx.northgravity.com/"
  -H "Authorization: Bearer yourAccessToken"

curl "https://api.obx.northgravity.com/"
  -u username:password ...

Change Password

Allows the user to change their password.

curl -X POST
  https://api.obx.northgravity.com/auth/changePassword
  -d '{
      "password": "new user password"
    }'

If successful, the above command returns status code 200, otherwise please check Errors section.

HTTP Request

POST https://api.obx.northgravity.com/auth/changePassword

Request Body

Parameter	Description
password	new user password

Log In

This endpoint returns a jwt access token and a refresh token. When the access token expires, the refresh token can be used to generate a new one. You will need to use Basic Auth to retrieve the jwt tokens.

curl -u 'login:password' 
  https://api.obx.northgravity.com/auth/login

If successful, the above command returns a status code 200 and token, otherwise please check Errors section.

{
    "token": "your access token",
    "refreshToken": "your refresh token"
}

HTTP Request

GET https://api.obx.northgravity.com/auth/login

Request Header

Parameter	Description
userName	userName of account
password	password of account

Refresh Access Token

This endpoint returns a new access token.

curl -X POST
  https://api.obx.northgravity.com/auth/refresh
  -d '{
    "refreshToken": "your refresh token"
    }'

If successful, the above command returns a status code 200 and token, otherwise please check Errors section.

{
    "token": "your access token",
    "refreshToken": "your refresh token"
}

HTTP Request

POST https://api.obx.northgravity.com/auth/refresh

Request Body

Parameter	Description
refreshToken	your refresh token

Log out

Log out the user by invalidating the refresh token.

curl -X POST
  https://api.obx.northgravity.com/auth/logout
  -H "Authorization: Bearer yourAccessToken"
  -d '{
    "refreshToken": "your refresh token"
    }'

If successful, the above command returns status code 200, otherwise please check Errors section.

HTTP Request

POST https://api.obx.northgravity.com/auth/logout

Request Body

Parameter	Description
refreshToken	your refresh token

Time Series

Search Time Series Data

curl -X POST  
  https://api.obx.northgravity.com/ts/stream?size=10&order=ASC
  --header 'Content-Type: application/json'
  --header 'Authorization: Bearer ****'
  -d '{
        "startDate": null,
        "endDate": null,
        "keys": [
          {
            "symbols": {
              "Symbol": "*"
            },
            "metadatas": {},
            "groupName": "GroupName",
            "pattern": true,
            "metaDataExactMatch": true
          }
        ],
        "range": "LAST",
        "lastType": "VALUE_COLUMN",
        "lastTypeAmount": 1,
        "metadata": true
      }'

Response

Symbol	Date (UTC)	Close	High	Low	OBXCode (S)	Open	PeriodAbs (S)	PeriodEnd (D)	PeriodRel (S)	PeriodStart (D)	PeriodType (S)	TenorGeneric (S)	TenorUnique (S)	Currency (MD-S)	DataGranularity (MD-S)	DataType (MD-S)	Description (MD-S)	FuturesRoot (MD-S)	Market (MD-S)	Product (MD-S)	Source (MD-S)	SourceRegion (MD-S)	TimeZone (MD-S)	Units (MD-S)	ValueType (MD-S)
product_AC_M.202702	2025-02-07T12:00:00	12.1917	12.2366	12.1169	16d67039-8300-4aa2-845f-c39a3c176bc8	12.1748	2027-02	2027-02-28	25	2027-02-01	Month	M24	G27	USD	Intraday	Futures	product LNG - OBX	product	Natural Gas	LNG	OBX	Europe	UTC	MMBTU	Pricing
product_CC_M.007	2025-02-07T12:00:00	16.6485	16.6592	16.5523	16d67039-8300-4aa2-845f-c39a3c176bc8	16.5936	2025-08	2025-08-31	7	2025-08-01	Month	M06	Q25	USD	Intraday	CC Month	product LNG - OBX	product	Natural Gas	LNG	OBX	Europe	UTC	MMBTU	Pricing
product_CC_M.012	2025-02-07T12:00:00	15.2477	15.2769	15.1433	16d67039-8300-4aa2-845f-c39a3c176bc8	15.186	2026-01	2026-01-31	12	2026-01-01	Month	M11	F26	USD	Intraday	CC Month	product LNG - OBX	product	Natural Gas	LNG	OBX	Europe	UTC	MMBTU	Pricing

HTTP Request

POST https://api.obx.northgravity.com/ts/stream?size=<size>&order=<order>

URL Parameters

Parameter	Description	Optional
size	The maximum number of rows displayed at once.	true
order	Sort order: ASC for ascending, DESC for descending. Defult order is descending.	true

Request Body

Top-Level Fields

Parameter	Type	Description	Optional
keys	array of objects	Array of key objects. Minimum 1 key is required. See Fields inside keys for object structure.	no
range	string	Defines how the search period is calculated. (see Parameter Range)	yes
startDate	string	Date (ISO 8601). Start of the date range. Results earlier than this date are excluded. Example: "2025-09-01T00:00:00". Only works when range = "BETWEEN" or when range = "LAST" with lastType = "VALUE_COLUMN".	yes
endDate	string	Date (ISO 8601). End of the date range. Results later than this date are excluded. Example: "2025-09-02T00:00:00". Only works when range = "BETWEEN" or when range = "LAST" with lastType = "VALUE_COLUMN".	yes
lastType	string	Defines the type of the “last period”. (see Parameter Range)	yes
lastTypeAmount	integer	Specifies the number of periods for the last selected type. (see Parameter Range)	yes
metadata	bool	If true, includes symbol metadata in the response. Default: false	yes

Fields inside keys

Field	Type	Description	Optional
groupName	string	Group name for the key.	no
symbols	key-value	Map of name-value pairs. Example: { "Code": "AL123", "Exchange": "ICE" }, where Code is column name and AL123 is value from this column.	no
metadatas	key-value	Map of metadata attributes. Example: { "DataType": "CC Month" }, where DataType is column name and CC Month is value from this column. If multiple are provided, the last one takes precedence.	yes
pattern	bool	Required if any symbols or metadatas value equals "*". Enables pattern matching.	yes
patternExactMatch	boolean	When true, validates that symbol column names match exactly. Requires specifying all column names for the symbols in the request. Defaults to false.	Yes
symbolValuesExactMatch	boolean	Match exact symbol values only. If true, returns only exact matches (e.g. "MAR"). If false, also returns values where the symbol is combined with other text using any delimiters (e.g. "AB-MAR"). Defaults to false.	Yes
metaDataExactMatch	boolean	Match exact metadata values only. If true, returns only exact matches (e.g. "MET"). If false, also returns values where the symbol is combined with other text using any delimiters (e.g. "HUB-MET"). Defaults to false.	Yes

Parameter Range

Possible values for range:

• "Between" – use startDate and endDate parameters to define exact time period to search in.
• "LAST" – use lastType and lastTypeAmount.
  • lastType - can be one of: "MINUTE", "HOUR", "DAY", "MONTH", "YEAR", "YEAR_TO_DATE", "VALUE", "VALUE_COLUMN"

Errors

The NG API uses the following error codes:

Error Code	Meaning
400	Bad Request -- The request you sent is incorrect.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The requested resource is hidden and may be accessed by the administrators only.
404	Not Found -- The specified resource could not be found.
405	Method Not Allowed -- You tried to access a resource with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- The resource requested has been removed from our servers.
418	I'm a teapot.
429	Too Many Requests -- You're requesting too many times! 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.

API Examples

The following are examples of common use cases of our API.

Downloading the latest values for the current time

{
    "startDate": null,
    "endDate": null,
    "keys": [
        {
            "symbols": {
                "Symbol": "*"
            },
            "metadatas": {},
            "groupName": "GroupName",
            "pattern": true,
            "metaDataExactMatch": true
        }
    ],
    "range": "LAST",
    "lastType": "VALUE_COLUMN",
    "lastTypeAmount": 1,
    "metadata": true
}

Downloading the latest two values for a specific time

{
  "startDate": "2025-02-07T12:00:00",
  "endDate": "2025-02-08T12:00:00",
  "keys": [
    {
      "symbols": {
        "Symbol": "*"
      },
      "metadatas": {},
      "groupName": "GroupName",
      "pattern": true,
      "metaDataExactMatch": true
    }
  ],
  "range": "LAST",
  "lastType": "VALUE_COLUMN",
  "lastTypeAmount": 1,
  "metadata": true
}

Downloading data for a specific product within a defined date range

{
  "startDate": "2025-02-07T12:00:00",
  "endDate": "2025-02-07T12:10:00",
  "keys": [
    {
      "symbols": {
        "Symbol": "*"
      },
      "metadatas": {
        "FuturesRoot": "TFU"
      },
      "groupName": "GroupName",
      "pattern": true,
      "metaDataExactMatch": true
    }
  ],
  "range": "BETWEEN",
  "metadata": false
}