This guide provides detailed instructions on how to use QX Query API to interact with the two available methods. QX Query is a powerful API product that allows easy retrieval of complex market data information. It provides users with access to a wide variety of market data properties, including price data, volume data, and other relevant metrics. With QX Query, users can quickly and easily retrieve the data they need to integrate with any applications/systems.

1. POST JOB Request

The POST request is used to create a job that will run a QX Query report. To create a job, you will need to include the following parameters in your request:

Endpoint

The endpoint for this method is https://api.quodd.com/universal/jobs.

Parameters

• template: This is the name of the template which will be used to generate the job report. This is a required parameter. The template can be any one of the pre-defined templates which are available in Quodd’s Universe + product. Or the user can create a custom template using the QX Query UI in Universe +. The templates list the properties/data elements to be included in the report response for the given list of identifiers.

• identifiers: This is a list of identifiers that should be used in the job. This is a required parameter.

• startDate: This is the start date for the job. This is a required parameter.

• endDate: This is the end date for the job. This is a required parameter.

• extendedoptions: Optional parameters for specific corporate action template job requests.
  • CorporateActionsByEffectiveDate: This is a boolean parameter that specifies whether corporate actions should be included in the report by the effective date.
  • DividendsByExDate: This is a boolean parameter that specifies whether dividends should be included in the report by the ex-date.

Response

Once the job is created, the API will return a response that includes the following information:

• jobid: This is the ID of the newly created job.

• jobstatus: This is the status of the job. The status will be either "Accepted" or "Failed".

Sample Request

{
    "Template": 'pricing' ,
    "Identifiers": ['MSFT', 'IBM', 'AAPL','CSCO', '1232323232323','SPLK'],
    "JobParameters": {
        "startDate": '2023-05-05' ,
        "endDate": '2023-06-02'
    }
}

Sample Response Body

{
    "JobID": "1686927711346",
    "JobStatus": "Accepted"
		"Message": "Job Accepted"
}

2. GET JOB STATUS Request

The GET JOB INFO request is used to check the status of a previously created job. To retrieve the status of a job, you will need to include the following parameters in your request:

Endpoint

The endpoint for this method is https://api.quodd.com/universal/jobs/{JobID}.

Parameters

• JobID: This is the ID of the job for which you want to retrieve results. This is a required parameter.

Response

Once the API has retrieved the results of the job, it will return a response that includes the following information:

• jobid: This is the ID of the job.

• jobstatus: This is the status of the job.

• submittimestamp: This is the time when the job was submitted.

Sample Response Body

{
    "JobInfo": {
        "JobID": "1686853962515",
        "JobStatus": "completed",
        "SubmitTimestamp": 1686853963
    }
}

3. GET JOB RESULTS Request

The GET request is used to retrieve the results of a previously created job. To retrieve the results of a job, you will need to include the following parameters in your request:

Endpoint

The endpoint for this method is https://api.quodd.com/universal/Jobs/{JobID}/results/{resultformat}.

Parameters

• JobID: This is the ID of the job for which you want to retrieve results. This is a required parameter.

• resultformat: This is the format of the result. This is an optional parameter that can be set to either "csv", “pipe” or "json". If not specified, the default format is "csv".

Response

Once the API has retrieved the results of the job, it will return a response that includes the following information:

• result: This is the result of the job in either CSV, PIPE or JSON format.

Sample Request for a csv response

https://api.quodd.com/universal/jobs/1686927711346/results/csv

Sample Response for a csv response

requestedIdentifier,Category,MIC,LocalCode,ISIN,Currency,PriceDate,Open,High,Low,Close,Mid,Ask,Last,Bid,Bidsize,Asksize,TradedVolume,SecurityID,MktCloseDate,VolFlag,IssuerName,SecurityType,SecurityTypeDescription,SEDOL,CUSIP,PrimaryExchange,Exchange,TradedValue,TotalTrades,CloseType
MSFT,Price,USCOMP,MSFT,US5949181045,USD,2023-06-06,335.33,335.37,332.17,333.68,,333.66,333.68,333.65,9,9,20396223,39827,2023-06-06,A,Microsoft Corporation,EQS,Common Equity,2588173,594918104,USNASD,USCOMP,,339155,CC
MSFT,Price,USCOMP,MSFT,US5949181045,USD,2023-06-05,335.22,338.5599,334.6601,335.94,,335.96,335.94,335.94,19,12,21307053,39827,2023-06-05,A,Microsoft Corporation,EQS,Common Equity,2588173,594918104,USNASD,USCOMP,,374520,CC

Sample Request for a JSON response

https://api.quodd.com/universal/jobs/1686927988492/results/json

Sample Response for a JSON response

{
    "data": {
        "universalData": {
            "priceData": [
                {
                    "requestedIdentifier": "MSFT",
                    "MIC": "USCOMP",
                    "LocalCode": "MSFT",
                    "ISIN": "US5949181045",
                    "Currency": "USD",
                    "PriceDate": "2023-06-06",
                    "Open": 335.33,
                    "High": 335.37,
                    "Low": 332.17,
                    "Close": 333.68,
                    "Mid": null,
                    "Ask": 333.66,
                    "Last": 333.68,
                    "Bid": 333.65,
                    "Bidsize": 9,
                    "Asksize": 9,
                    "TradedVolume": "20396223",
                    "SecurityID": 39827,
                    "MktCloseDate": "2023-06-06",
                    "VolFlag": "A",
                    "IssuerName": "Microsoft Corporation",
                    "SecurityType": "EQS",
                    "SecurityTypeDescription": "Common Equity",
                    "SEDOL": "2588173",
                    "CUSIP": "594918104",
                    "PrimaryExchange": "USNASD",
                    "Exchange": "USCOMP",
                    "TradedValue": null,
                    "TotalTrades": 339155,
                    "CloseType": "CC"
                },
                {
                    "requestedIdentifier": "MSFT",
                    "MIC": "USCOMP",
                    "LocalCode": "MSFT",
                    "ISIN": "US5949181045",
                    "Currency": "USD",
                    "PriceDate": "2023-06-05",
                    "Open": 335.22,
                    "High": 338.5599,
                    "Low": 334.6601,
                    "Close": 335.94,
                    "Mid": null,
                    "Ask": 335.96,
                    "Last": 335.94,
                    "Bid": 335.94,
                    "Bidsize": 19,
                    "Asksize": 12,
                    "TradedVolume": "21307053",
                    "SecurityID": 39827,
                    "MktCloseDate": "2023-06-05",
                    "VolFlag": "A",
                    "IssuerName": "Microsoft Corporation",
                    "SecurityType": "EQS",
                    "SecurityTypeDescription": "Common Equity",
                    "SEDOL": "2588173",
                    "CUSIP": "594918104",
                    "PrimaryExchange": "USNASD",
                    "Exchange": "USCOMP",
                    "TradedValue": null,
                    "TotalTrades": 374520,
                    "CloseType": "CC"
                }
            ]
        }
    }
}

4. GET JOB EXCEPTIONS Request

The GET request is used to retrieve any exception results of a previously created job. To retrieve the exceptions which were generated as part of a prior job, you will need to include the following parameters in your request:

Endpoint

The endpoint for this method is https://api.quodd.com/universal/Jobs/{JobID}/exceptions/{resultformat}.

Parameters

• JobID: This is the ID of the job for which you want to retrieve results. This is a required parameter.

• resultformat: This is the format of the result. This is an optional parameter that can be set to either "csv" or "json". If not specified, the default format is "csv".

Response

Once the API has retrieved the results of the job, it will return a response that includes the following information:

• result: This is the result of the job in either CSV or JSON format.

Sample Request for exceptions

https://api.quodd.com/universal/jobs/1686927711346/exceptions/csv

Sample Response for exceptions response

identifier
1232323232323

5. GET LIST JOBS Request

The GET LIST JOBS request will return a collection of all jobs which were submitted. To retrieve the list of all jobs, you will need to include the following parameters in your request:

Endpoint

The endpoint for this method is https://api.quodd.com/universal/jobs.

Parameters

• None

Response

Once the API has retrieved the results of the job, it will return a response that includes the following information:

• jobid: This is the ID of the job.

• jobstatus: This is the status of the job.

• submittimestamp: This is the time when the job was submitted.

Sample Response

{
    "Jobs": [
        {
            "JobID": "1641236048372",
            "JobStatus": "completed",
            "SubmitTimestamp": 1641409499
        },
        {
            "JobID": "1641236178935",
            "JobStatus": "completed",
            "SubmitTimestamp": 1641409499
        },
        {
            "JobID": "1641236447999",
            "JobStatus": "completed",
            "SubmitTimestamp": 1641409499
        },
        {
            "JobID": "1641236611000",
            "JobStatus": "processing",
            "SubmitTimestamp": 1641409499
        }
		]
}

Getting Authorization Token

In order to access QX Query API, please use the credentials provided to you to get the token.

⚠️ Important Update. - The authentication endpoint has been updated. Clients must use the new API URL

Authentication Endpoint

• Old (Deprecated):

  https://auth.quodd.com/api/login

• New (Required):

  https://authn.quodd.com/v1/api/login

Sample CURL command to get the token.

curl -X POST --location 'https://authn.quodd.com/v1/api/login' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "clientusername",
    "password": "password",
    "redirect_url": "https://app.quodd.com",
    "firmcode": "quodddst"
  }'

Sample bash script to trigger a QX Query API and review results

#!/usr/bin/env bash

###################################################
## Usage:
#
# > ./example.sh {username} {template_name}
#
#
## prerequisites ##
# - curl
# - jq

####################################################
# Step 1:  Retrieve an access token
####################################################
echo "retrieve the token"
username="$1"
template="$2"

# Read Password
echo -n Password:
read -s password
echo ""

# Make the API request and capture the token from the response
auth_data='{ "username": "'"$username"'", "password": "'"$password"'", "firmcode": "quodddst", "redirect_url": "https://app.quodd.com" }'
response=$(curl -s -X POST -H "Content-Type: application/json" -d "$auth_data" "https://authn.quodd.com/v1/api/login")
token=$(echo "$response" | jq -r '.token')
if [ $token == "null" ]; then
  echo "authentication failed"
  exit -1
fi

####################################################
# Step 2: Submit the Job
####################################################

job_request_json='{"Template": "'"$template"'", "Identifiers": ["MSFT","IBM", "AAPL", "CSCO", "123231423412"], 
"JobParameters": { "startDate": "2023-05-05", "endDate": "2023-06-02" }}'

#post the job request to the api
job_response=$(curl -s -X POST  \
  -H "Authorization: Bearer $token" \
  -H "Accept: application/json" \
  -H "Content-Type:application/json" \
  -d "$job_request_json" \
  "https://api.quodd.com/universal/jobs")

jobid=$(echo "$job_response" | jq -r '.JobID')
if [ $jobid == "" ]; then
  echo "Submit Job failed."
  exit -1
fi

# Output the captured jobid
echo "Job ID: $jobid"


####################################################
# Step 3: Poll until complete and download results
####################################################
attempts=0
while [ true ]; do
  attempts=$((attempts+1))

  #call the api
  job_status_response=$(curl -s -w "%{http_code}" -H "Content-Type: application/json" -H "Authorization: Bearer $token" 
"https://api.quodd.com/universal/jobs/$jobid")

  #extract response values
  http_code=$(tail -n1 <<< "$job_status_response")  # get the last line
  content=$(sed '$ d' <<< "$job_status_response")   # get all but the last line which contains the status code

  if [ $http_code != 200 ]; then
    if ((attempts > 5)); then echo "unexpected error occured."; break; fi
    echo "<re-checking status in 3 seconds>"
    sleep 3; continue;
  fi

  status=$(echo "$content" | jq -r '.JobInfo.JobStatus')
  echo $status

  if [ "$status" == "failed" ]; then
    echo "job failed."
    break;
  fi

  if [ "$status" == "completed" ]; then
    echo "downloading results.json, results.csv and exceptions.txt"

    # Make the API request and save the results to a file
    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer $token" -o "results.json" 
"https://api.quodd.com/universal/jobs/$jobid/results/json"
    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer $token" -o "results.csv" 
"https://api.quodd.com/universal/jobs/$jobid/results/csv"
    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer $token" -o "exceptions.txt" 
"https://api.quodd.com/universal/jobs/$jobid/exceptions/json"
    break
  fi

done
echo "DONE!"

Known Beta Limitations

• Identifiers are limited to 25K or less.

• Date Range support is 3 months.

• Template names cannot have spaces or special characters

• Parameter names are case sensitive

Detailed quota limit per template

Here are the limitations for each template:

• Intraday: 3000 (limited by GRPC API as it supports 3000 identifiers per request).

• Descriptive/Fundamental Data: This template runs independent of date range. Per job request max 30K identifiers are allowed.

• Corporate Actions / Dividends:

• Tips Information: There are a total of 64 identifiers in case tips and all works for any date range.

• Call Schedules: This template runs independent of date range. Per job request maximum 60k identifiers are allowed.

• Put Schedules: This template runs independent of date range. Per job request maximum 60k identifiers are allowed.

• Sink Schedules: This template runs independent of date range. Per job request maximum 60k identifiers are allowed.

• Bond Redemptions: This template runs independent of date range. Per job request maximum 60k identifiers are allowed.

• Industry Classification: This template runs independent of date range. Per job request maximum 30K identifiers are allowed.

Conclusion

QX Query is a powerful API product that allows easy retrieval of complex market data information. With this guide, you should now be able to create and retrieve reports using the QX Query API.