API Examples

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

Pre-Requisites

You must have been on-boarded to the XSignals platform and have been entitled to the appropriate data products.
You will need to authenticate to the XSignals platform to obtain the bearer token. For more information, see: Authentication

Downloading a File via cURL

This walk through uses 3 steps to retrieve the latest file contents for a given group.

List Available Groups

Copy

Copied

curl --request GET 'https://api.xsignals.xpansiv.com/file/group/' --header 'Authorization: Bearer <REDACTED>'

Copy

Copied

{
  "from": 0,
  "totalSize": 2,
  "items": [
    {
      ...
      "groupId": 1234,
      "name": "CBL_Active Orders Voluntary Carbon",
      "description": "Carbon Active orders by date on CBL.",
      "type": "DATA",
      "createTime": 1632871153976,
      "fields": []
    },
    ...
  ]
}

Finding Latest File in Given Group

Copy

Copied

curl --request GET \ 
'https://api.xsignals.xpansiv.com/file/search?size=1&query=groupName%3dCBL_Active%20Orders%20Voluntary%20Carbon&sortBy=arrivalTime&sortOrder=desc' \ 
--header 'Authorization: Bearer <REDACTED>'

Copy

Copied

{
  "from": 0,
  "totalSize": 34,
  "items": [
    {
      "fileName": "Orders Active Voluntary Carbon.csv",
      "fileType": "NCSV",
      "groupName": "CBL_Active Orders Voluntary Carbon",
      "fid": "69a432b6-9526-4d92-8a89-d86330ca95c4",
      "fields": {
        ...
      },
      ...
    }
  ]
}

Downloading a File

Copy

Copied

curl --request GET \
'https://api.xsignals.xpansiv.com/file/69a432b6-9526-4d92-8a89-d86330ca95c4/download' \ 
--header 'Authorization: Bearer <REDACTED>'

Copy

Copied

Instrument,Market,Order Ref,Original,Side,Date(America/New_York),Balance,Ccy(S),Country(S),Date In(S),Instrument Mkt Name(S),Instrument Name(S),Price,Project ID(S),Project Type(S),Quantity,Time In(S),Type(S),ValueTax,Vintage(S),TimeZone(MD-S)
GEO,SIP,0001234567,0001234567,BID,2021-11-16T16:00:00,5000.00,USD,,2021.11.05,GEO-VCS,Global Emissions Offset,9.99,,,5000.00,17:28:39,LIMIT,0.00,,America/New_York
GEO,SIP,0007898765,0007898765,ASK,2021-11-16T16:00:00,10000.00,USD,,2021.11.08,GEO-VCS,Global Emissions Offset,9.99,,,10000.00,18:27:55,LIMIT,0.00,,America/New_York
...

Instructions

List Available Groups - Retrieve the list of groups you are entitled to.
- HTTP Request : curl --request GET 'https://api.xsignals.xpansiv.com/file/group/' --header 'Authorization: Bearer <REDACTED>'
- URL Parameters :
- header -> Authorization: Bearer <>
- Note the name of the group you would like to search.
Find Latest File in Given Group - Retrieves the details of latest file available within a given group.
- HTTP Request : curl --request GET 'https://api.xsignals.xpansiv.com/file/search?size=1&query=groupName%3d<groupName>&sortBy=arrivalTime&sortOrder=desc' --header 'Authorization: Bearer <REDACTED>'
- URL Parameters :
  - header -> Authorization: Bearer <>
  - query -> query=groupName%3d<groupName>
  - Use the group name returned in step 1.
  - Important : The query string MUST be urlencoded.
- Note the fid of the file response returned above.
Downloading a File - Download the contents of the latest file.
- HTTP Request : curl --request GET 'https://api.xsignals.xpansiv.com/file/<fid>/download' --header 'Authorization: Bearer <REDACTED>'
- URL Parameters :
  - header -> Authorization: Bearer <>
  - file id -> <fid>
  - The fid returned in step 2.

See the following links for more details:

Pulling Deltas from Time Series for Given Group and Time Range

This walk through uses 2 steps to retrieve the latest values from time series for a given group and time range.

List Available Groups

Copy

Copied

curl --request GET 'https://api.xsignals.xpansiv.com/file/group/' --header 'Authorization: Bearer <REDACTED>'

Copy

Copied

{
  "from": 0,
  "totalSize": 2,
  "items": [
    {
      ...
      "groupId": 1234,
      "name": "CBL_Active Orders Voluntary Carbon",
      "description": "Carbon Active orders by date on CBL.",
      "type": "DATA",
      "createTime": 1632871153976,
      "fields": []
    },
    ...
  ]
}

Request Deltas for Given Group and Date Range

Copy

Copied

curl --location --request POST 'https://api.xsignals.xpansiv.com/ts' \
--header 'Authorization: Bearer <REDACTED>' \
--data-raw '{
    "corrections": true,
    "delta": true,
    "range": "BETWEEN",
    "startDate": "2022-01-20T19:38:00",
    "endDate": "2022-01-20T19:49:59",
    "formatType": "NCSV",
    "groupName": "CBL_Active Orders Voluntary Carbon"
}
'

Copy

Copied

Instrument,Market,Order Ref,Original,Side,Date(America/New_York),Balance,Ccy(S),Country(S),Date In(S),Instrument Mkt Name(S),Instrument Name(S),Price,Project ID(S),Project Type(S),Quantity,Time In(S),Type(S),ValueTax,Vintage(S)
INST1,SIP,123,321,BID,2022-01-01T16:00:00,20,USD,,2022.01.01,INST1-SIP,Instrument 1 Emission Offset,1.23,,,20,9:54:01,LIMIT,,
INST2,Voluntary,456,654,ASK,2022-01-01T16:00:00,1000,USD,Asia/China,2022.01.01,INST2-Voluntary,Instrument 2,2.3,ABC,Biogas - Cogeneration,1300,8:10:01,LIMIT,,
INST3,Voluntary,789,987,ASK,2022-01-01T16:00:00,20000,USD,Asia/India,2022.01.01,INST3-Voluntary,Instrument 2,4.5,2026,Energy Industries - renewable/non-renewable sources,500,13:48:17,AON,,

Instructions

List Available Groups - Retrieve the list of groups you are entitled to.
- HTTP Request : curl --request GET 'https://api.xsignals.xpansiv.com/file/group/' --header 'Authorization: Bearer <REDACTED>'
- URL Parameters :
  - header -> Authorization: Bearer <>
- Note the name of the group you would like to search.
Get Time Series Data - Retrieve time series deltas for a given group and date range.
- HTTP Request : curl --location --request POST 'https://api.ng.dev.xpansiv.com/ts' \ --header 'Authorization: Bearer <REDACTED>' \ --data-raw '{ <SEE BODY PARAMETERS> }'
- URL Parameters :
  - header -> Authorization: Bearer <>
- Body Parameters :
  - corrections -> [false / true]
  - delta -> [false / true]
  - range -> [BETWEEN]
  - startDate -> date from (ISO 8601)
  - endDate -> date to (ISO 8601)
  - formatType -> [NCSV / STANDARD]
  - groupName -> Name of group to be searched

See the following links for more details:

Automating Time Series Pulls

Copy

Copied

#!/bin/bash
GROUPNAME=CBL_Active%20Orders%20Voluntary%20Carbon
#GROUPNAME=CBL_Trades%20Voluntary%20Carbon

SYMS=$(curl -s -n "https://api.xsignals.xpansiv.com/ts/symbol/search?size=500&query=groupName=${GROUPNAME}&tokenExpiration=10m")
 
ITEMS=$(jq -r '.items[] | {symbols, groupName}' <<< "$SYMS" | jq -s '.')
TOTALSIZE=$(jq -c '.totalSize' <<< "$SYMS")
LENGTH=$(jq -r '.items | length' <<< "$SYMS")
TOKEN=$(jq -r '.nextPageToken' <<< "$SYMS")
 
PL="{\"formatType\": \"NCSV\", \"keys\": ${ITEMS} }"
curl -s -n "https://api.xsignals.xpansiv.com/ts" -d "${PL}" > data.csv
 
while [ $LENGTH -lt $TOTALSIZE ]; do
    SYMS=$(curl -s -n "https://api.xsignals.xpansiv.com/ts/symbol/search?size=500&query=groupName=${GROUPANME}&tokenExpiration=10m&nextPageToken=${TOKEN}")
    ITEMS=$(jq -r '.items[] | {symbols, groupName}' <<< "$SYMS" | jq -s '.')
    NLENGTH=$(jq -r '.items | length' <<< "$SYMS")
    PL="{\"formatType\": \"NCSV\", \"keys\": ${ITEMS} }"
    curl -s -n "https://api.xsignals.xpansiv.com/ts" -d "${PL}" | grep -v 'Instrument,Market' >> data.csv
    let LENGTH=LENGTH+NLENGTH
done

A sample bash script that allows you to iterate through a days results concatenating the results in a file named data.csv.

Note: This script requires jq to be available locally.