Equity Short Interest Reporting Application Programming Interface (API)

Pursuant to FINRA Rule 4560, member firms are required to report total short positions in all customer and proprietary firm accounts in all equity securities to FINRA on a bi-monthly basis. These filings are made online using the Short Interest reporting system accessible via Firm Gateway at firms.finra.org.

All firms that report short interest to FINRA are responsible for maintaining current and previous cycle short interest reports pursuant to SEC recordkeeping requirements. The web-based system is the only method for reporting the firm’s proprietary and customer short positions in NASDAQ, NYSE, NYSE American, NYSE Arca, Bats and OTC equity securities.

Equity Short Interest Reporting API

API name API description API type
issueSymbolIdentifier Issue symbol identifier String
settlementDate Settlement Date (yyyy-MM-dd) Date
issueName Name of the issue String
marketCategoryCode Indicates whether the issue is OTC Bulletin Board (U) or non-Bulletin Board (u) String
marketCategoryCode Describes the code that indicates whether the issue is OTC Bulletin Board (OTCBB) or non-Bulletin Board (Other OTC)" String
currentShortShareNumber The total number of shares in the issue that are reflected on the books and records of the reporting firms as short as defined by Rule 200 of Regulation SHO as of the current cycle’s designated settlement date. Number
previousShortShareNumber The total number of shares in the issue that are reflected on the books and records of the reporting firms as short as defined by Rule 200 of Regulation SHO as of the prior cycle’s designated settlement date. Number
changePercent Change in Shares Short from Previous Cycle: Difference in short interest between the current cycle and the previous cycle Number
percentageChangefromPreviousShort The percent change from the current cycle's short interest compared to the previous cycle's short interest. Formula: (Current Cycle Short Interest - Previous Cycle Short Interest) / Previous Cycle Short Interest, x 100, Rounded to Hundredths. Number
averageShortShareNumber Total Volume or Adjusted Volume in case of splits / Total trade days between (previous settlement date + 1) to (current settlement date). The NULL values are translated as zero Number
daysToCoverNumber The number of days of average share volume it would require to buy all of the shares that were sold short during the reporting cycle. Formula: Short Interest / Average Daily Share Volume, Rounded to Hundredths. 1.00 will be displayed for any values equal or less than 1 (i.e., Average Daily Share is equal to or greater than Short Interest). N/A will be displayed If the days to cover is Zero (i.e., Average Daily Share Volume is Zero). Number

API Status Codes


Explains available API call parameters

HTTP Status Code Reason
200 OK
201 Created
204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
406 Not Acceptable
409 Conflict
415 Unsupported Media Type
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout

Request Parameters


Explains available API call parameters

Parameter Value/Example Description Applies to Data Type
group otcMarket Name of the group or category of the data. Setting this parameter returns only dataset(s) belonging to that group. All string
name equityShortInterest Unique name of the data within the group. Setting this parameter with group returns one unique dataset. Setting this parameter without group can return one or more dataset(s) across group(s). All string
fields "fields" : ["settlementDate"," issueName"] Comma delimited list of field names to retrieve. Default is all fields. /data  
sortFields "sortFields" : [ "- changePercent" ] Comma delimited list of field names to sort by. You can prepend a + or - before the field name to specify an ascending or descending sort on that field respectively. /data string
compareFilters "compareFilters" : [ {

"fieldName" : "issueSymbolIdentifier",

"fieldValue" : "AAPL",

compareType" : "EQUAL" } ]
List of value comparison filters POST /data  
dateRangeFilters "dateRangeFilters" : [ {

"startDate" : "2017-02-10",

"endDate" : "2017-05-10",

"fieldName" : " settlementDate" } ]
List of date range filters. POST /data  
domainFilters "domainFilters" : [ {

"fieldName" : " marketCategoryCode",

"values" : [ "u", "U"] } ]
List of domain filters. POST /data  
offset "offset" : 10 Record number to start with (exclusive). Default is 0. Range of records to be returned is offset record plus limit. If offset is 0 and limit is 20, then records 1 to 20 are returned for a total of 20 records. If offset is 10 and limit is 10, then records 11 to 20 are returned. /data number
limit "limit" : 10 Number of records to return. The default value is 1000. The max value is 100000. To get all records, user can iterate calls increasing the offset value until no more records are returned. /data number
delimiter "delimiter" : "|" Can be used to specify a character delimiter if the Accept header is text/plain. Default value is a comma. Allowed values are pipe, comma, tab, or control A. Reference https://www.w3schools.com/tags/ref_urlencode.asp for encoding standards in URLs. /data  
quoteValues "quoteValues" : false Can be used to specify if values should be quoted if the Accept header is text/plain. /data  

Request Header Parameters


Request and Response headers explains metadata associated with the API

Parameter Value/Example Description Applies to Data Type
Accept text/plain Can be used to specify a format for the data returned.

Supports (application/json, text/plain). If the native data format cannot convert between JSON/CSV, then a status code of 400 will be returned.

If an unsupported MIME type is supplied, then a 406 is returned.
/data string
data-api-version   Used to specify version of the API to use.    

Request Headers


Parameter Value/Example Description Applies to Data Type
Content-Type application/json, text/plain Set to match the format of the request unless an error occurred, in which case it will be application/json. /data string
Record-Total   Total records found at the time of request for the given query excluding limit. /data  
Record-Offset   Record offset number. /data  
Record-Limit   Record limit for the query. /data  

GET /metadata/group/otcMarket/name/EquityShortInterest


Returns the data dictionary in JSON format. It details the name, type and description of each column.

Request URL

https://api.finra.org/metadata/group/OTCMarket/name/EQUITYSHORTINTEREST

Request Headers

{
  "Accept": "application/json"
}

Curl Command

curl https://api.finra.org/metadata/group/OTCMarket/name/EQUITYSHORTINTEREST

Response Body

{
  "datasetGroup" : "OTCMARKET",
  "datasetName" : "EQUITYSHORTINTEREST",
  "partitionFields" : [ "settlementDate" ],
  "fields" : [ {
    "name" : "issueSymbolIdentifier",
    "type" : "String",
    "description" : "Issue symbol identifier"
  }, {
    "name" : "settlementDate",
    "type" : "Date",
    "format" : "yyyy-MM-dd",
    "description" : "Settlement Date"
  }, {
    "name" : "issueName",
    "type" : "String",
    "description" : "Issue Name"
  }, {
    "name" : "marketCategoryCode",
    "type" : "String",
    "description" : "Indicates whether the issue is OTC Bulletin Board or non-Bulletin Board"
  }, {
    "name" : "marketCategoryDescription",
    "type" : "String",
    "description" : "Describes the code that indicates whether the issue is OTC Bulletin Board (U) or non-Bulletin Board (u)"
  }, {
    "name" : "currentShortShareNumber",
    "type" : "Number",
    "description" : "The total number of shares in the issue that are reflected on the books and records of the reporting firms as short as required by FINRA  Rule 4560 as of the current designated settlement date."
  }, {
    "name" : "previousShortShareNumber",
    "type" : "Number",
    "description" : "The total number of shares in the issue that are reflected on the books and records of the reporting firms as short as required by FINRA Rule 4560 as of the previous designated settlement date."
  }, {
    "name" : "changePercent",
    "type" : "Number",
    "description" : "Change in short interest between the current settlement date and the previous settlement date."
  }, {
    "name" : "percentageChangefromPreviousShort",
    "type" : "Number",
    "description" : "The percent change from the current settlement date's short interest compared to the previous settlement date's short interest. Formula: (Current Short Interest - Previous Short Interest) / Previous Short Interest, x 100, Rounded to Hundredths."
  }, {
    "name" : "averageShortShareNumber",
    "type" : "Number",
    "description" : "Total Short Interest Volume or Adjusted Short Interest Volume for securities with stock splits or dividends / Total trade days between (previous settlement date + 1) to (current settlement date). The NULL values are translated as zero."
  }, {
    "name" : "daysToCoverNumber",
    "type" : "Number",
    "description" : "The number of days of average trading volume it would require to buy to cover the entire quantity of short interest reported for the current settlement date. Formula: Short Interest / Average Daily Share Volume, Rounded to Hundredths. 1.00 will be displayed for any values equal or less than 1 (i.e., Average Daily Share is equal to or greater than Short Interest). N/A will be displayed If the days to cover is Zero (i.e., Average Daily Share Volume is Zero)."
  } ]
}






Response Headers

HTTP/1.1 200
Date: Tue, 18 Sep 2018 18:48:57 GMT
Content-Type: application/json
Content-Length: 965
Connection: keep-alive
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
data-api-version: 1
Expires: 0
Pragma: no-cache
Set-Cookie: JSESSIONID=1234567890ABCDE; Path=/; HttpOnly
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block

GET /partitions/group/otcMarket/name/EquityShortInterest


Returns a list of available primary partitions, and sub partitions if applicable. It also returns a list of partition fields. Primary partitions are generally by date

Request URL

https://api.finra.org/partitions/group/OTCMarket/name/EQUITYSHORTINTEREST

Request Headers

{
  "Accept": "application/json"
}

Curl Command

curl https://api.finra.org/partitions/group/OTCMarket/name/EQUITYSHORTINTEREST

Response Body

{
     "datasetGroup":"OTCMarket",
     "datasetName":"EQUITYSHORTINTEREST",
     "partitionFields":[" settlementDate"],
     "availablePartitions":
      [
          {"partitions":["2018-07-01"]},
          {"partitions":["2018-06-15"]},
          {"partitions":["2018-06-01"]}
     ]
}

Response Headers

HTTP/1.1 200
Date: Wed, 19 Sep 2018 18:06:42 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 204
Connection: keep-alive
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Expires: 0
Pragma: no-cache
Set-Cookie: JSESSIONID=1234567890ABCDE; Path=/; HttpOnly
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block

GET /data/group/otcMarket/name/EquityShortInterest


Returns data for the specified dataset with basic selection criteria. All data is returned synchronously in the HTTPS response stream.

Request URL

https://api.finra.org/data/group/otcMarket/name/EquityShortInterest

Request Headers

{
    "Accept": "application/json"
}

Curl Command

curl -X GET --header 'Accept: application/json' https://api.finra.org/data/group/otcMarket/name/EquityShortInterest

Response Body

[
   

{
        "issueSymbolIdentifier": "AAALF",
        "issueName": "Aareal Bank AG AKT",
        "marketCategoryDescription": "Other OTC",
        "marketCategoryCode": "u",
        "changePercent": 20.07,
        "currentShortShareNumber": 131471,
        "daysToCoverNumber": 999.99,
        "settlementDate": "2018-09-14",
        "previousShortShareNumber": 109497,
        "averageShortShareNumber": 0,
        "percentageChangefromPreviousShort": 21974
    }



]

Response Headers

HTTP/1.1 200
Date: Tue, 18 Sep 2018 19:08:56 GMT
Content-Type: application/json
Content-Length: 212
Connection: keep-alive
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
data-api-version: 1
Expires: 0
Pragma: no-cache
Record-Limit: 1
Record-Offset: 0
Record-Total: 182
Set-Cookie: JSESSIONID=1234567890ABCDE; Path=/; HttpOnly
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block

POST /data/group/otcMarket/name/EquityShortInterest


Returns data for the specified dataset with advanced selection criteria including value comparison and date range filters. All data is returned synchronously in the HTTPS response stream.

Request URL

https://api.finra.org/data/group/otcMarket/name/EquityShortInterest

Request Headers

{
    "Accept": "application/json"
}

Filters

Contents of compareFilter.json

{
	"compareFilters": 
	[{ 
		"compareType": "EQUAL", 
		"fieldName": " settlementDate ", 
		"fieldValue": "2018-09-14"  
	}] ,
	"limit":1
}

Curl Command

curl -L -d "@compareFilter.json" -H "Content-Type: application/json" -X
POST https://api.finra.org/data/group/otcMarket/name/EquityShortInterest

Response Body

   [
    {
        "issueSymbolIdentifier": "AAALF",
        "issueName": "Aareal Bank AG AKT",
        "marketCategoryDescription": "Other OTC",
        "marketCategoryCode": "u",
        "changePercent": 20.07,
        "currentShortShareNumber": 131471,
        "daysToCoverNumber": 999.99,
        "settlementDate": "2018-09-14",
        "previousShortShareNumber": 109497,
        "averageShortShareNumber": 0,
        "percentageChangefromPreviousShort": 21974
    }
] 

Response Headers

HTTP/1.1 200
Date: Tue, 18 Sep 2018 19:08:56 GMT
Content-Type: application/json
Content-Length: 212
Connection: keep-alive
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
data-api-version: 1
Expires: 0
Pragma: no-cache
Record-Limit: 1
Record-Offset: 0
Record-Total: 182
Set-Cookie: JSESSIONID=1234567890ABCDE; Path=/; HttpOnly
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block

GET /versions


Returns API version information. All responses are returned in JSON format with the Content-Type response header set to application/json.

Name Description
version Number denoting the version number
revisions List of revisions from last version.
datePublished Date this version was published.

Request URL

https://api.finra.org/versions

Request Headers

{
   "Accept": "application/json"
}

Curl Command

curl https://api.finra.org/versions

Response Body

[ {
  "version" : "1",
  "revisions" : "initial version",
  "datePublished" : "2018-09-18"
} ]

Response Headers

HTTP/1.1 200
Date: Tue, 18 Sep 2018 18:56:02 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 94
Connection: keep-alive
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Expires: 0
Pragma: no-cache
Set-Cookie: JSESSIONID=1234567890ABCDE; Path=/; HttpOnly
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block