URI Formats and Examples

URI Format

This is a general format of URL to DataFied API

{Protocol}://edgaronline.api.mashery.com/{Version}/{Endpoints}{Format}?{Parameters}appkey={API Key}

Name Description Required Default Values
Protocol HTTP protocol (HTTPS not supported) Yes http
Version Version of API: v2 or v1 Yes v2
Endpoints, Parameters Path to API method and parameters Yes Each API call is documented under each API resources
Response format Format of API response: .json or .xml No JSON|XML, Default response format is JSON
API Key Authorized API Key Yes

Please note that URLs need to be URL-encoded for every request.

Response Format

All DataFied APIs return JSON formatted responses, unless otherwise specified in the call being made.

http://edgaronline.api.mashery.com/v2/companies?primarysymbols=msft&appkey={APPKEY}

{
   "result": {
      "totalrows": 1,
      "rows": [
         {
            "rownum": 1,
            "values": [
               {
                  "field": "cik",
                  "value": "0000789019"
               },
               {
                  "field": "companyname",
                  "value": "MICROSOFT CORP"
               },
               {
                  "field": "entityid",
                  "value": 8528
               },
               {
                  "field": "primaryexchange",
                  "value": "Nasdaq Global Market"
               },
               {
                  "field": "primarysymbol",
                  "value": "MSFT"
               },
               {
                  "field": "siccode",
                  "value": "7372"
               },
               {
                  "field": "sicdescription",
                  "value": "Prepackaged Software"
               }
            ]
         }
      ]
   }
}

DataFied supports two formats: JSON and XML. To specify one format versus the other, please reference the examples listed below.

JSON

1. Specifying .json sufix

http://edgaronline.api.mashery.com/v2/companies.json?primarysymbols=msft&appkey={APPKEY}

2. Specifying headers

GET /v2/companies?primarysymbols=msft&appkey={APPKEY} HTTP/1.1
ApplicationKey: {APPKEY}
Host: edgaronline.api.mashery.com
Accept: application/json

 

Response
{
   "result": {
      "totalrows": 1,
      "rows": [
         {
            "rownum": 1,
            "values": [
               {
                  "field": "cik",
                  "value": "0000789019"
               },
               {
                  "field": "companyname",
                  "value": "MICROSOFT CORP"
               },
               {
                  "field": "entityid",
                  "value": 8528
               },
               {
                  "field": "primaryexchange",
                  "value": "Nasdaq Global Market"
               },
               {
                  "field": "primarysymbol",
                  "value": "MSFT"
               },
               {
                  "field": "siccode",
                  "value": "7372"
               },
               {
                  "field": "sicdescription",
                  "value": "Prepackaged Software"
               }
            ]
         }
      ]
   }
}
XML

1. Specifying .xml sufix

http://edgaronline.api.mashery.com/v2/companies.xml?primarysymbols=msft&appkey={APPKEY}

2. Specifying headers

GET /v2/companies?primarysymbols=msft&appkey={APPKEY} HTTP/1.1
ApplicationKey: {APPKEY}
Host: edgaronline.api.mashery.com
Accept: application/xml

 

Response
<response>
  <result>
    <totalrows>1</totalrows>
    <rows>
      <row>
        <rownum>1</rownum>
        <values>
          <value field="cik">0000789019</value>
          <value field="companyname">MICROSOFT CORP</value>
          <value field="entityid">8528</value>
          <value field="primaryexchange">Nasdaq Global Market</value>
          <value field="primarysymbol">MSFT</value>
          <value field="siccode">7372</value>
          <value field="sicdescription">Prepackaged Software</value>
        </values>
      </row>
    </rows>
  </result>
</response>

URI Examples

http://edgaronline.api.mashery.com/v2/corefinancials/ann?primarysymbols=MSFT&appkey={APPKEY}

http://edgaronline.api.mashery.com/v2/corefinancials/qtr?primarysymbols=MSFT&numperiods=3&appkey={APPKEY}

http://edgaronline.api.mashery.com/v2/companies?primarysymbols=MSFT&appkey={APPKEY}

http://edgaronline.api.mashery.com/v2/insiders/filers?issueids=539631&appkey={APPKEY}

 

Useful API Calls

Debug

Debug parameter helps developers investigate what happened during the call and what items were substituted if any during the call.

http://edgaronline.api.mashery.com/v2/corefinancials/ann.json?primarysymbols=MSFT&numperiods=3&debug=true&appkey={APPKEY}

"debug": {
     "primarysymbols":"MSFT",
     "numperiods":"3",
     "sortby":"PRIMARYSYMBOL ASC, PERIODENDDATE DESC",
     "limit":"25",
     "deleted":"false",
     "offset":"0",
     "fields":"CIK,COMPANYNAME,ENTITYID"
}

Pagination

When the amount of data returned in response is larger than the system defined rows, data pagination occurs. Navigation to a certain row in the paginated result set is possible via two parameters in the request for any resource: limit and offset. Limit defines the number of rows to be returned. Offset defines how many rows to skip as means to navigate to the specific page of results. Every response displays total number of rows in the system.

Limit

By default, if a developer does not specify any limit value, the system returns the first 25 rows. In other cases they can define an integer as a limit, using a value between 1 and 9999.

Example:

http://edgaronline.api.mashery.com/v2/companies?companynames=*micro*&limit=10&appkey={APPKEY}

This request will return 10 rows from total list of companies, with "micro" contained in the name.

Invalid request:

http://edgaronline.api.mashery.com/v2/companies?companynames=*micro*&limit=10000&appkey={APPKEY}

Response:

400 Bad Request
X-Mashery-Error-Code: ERR_403_DEVELOPER_INACTIVE
{
   "Message": "Parameter 'limit' has invalid value. Parameter should contain a value within the range of 1 - 9999."
}

Offset

If the total number of expected rows is a large value offset parameter can be useful to narrow the result set. By default the system returns 25 rows per page with offset = 0. To navigate to the page 2 of the request, set the offset = 26, which will pull data rows between 26 and 50. For page 3, define the offset = 51; each subsequent page can be called by using increments of 25.

Example:

http://edgaronline.api.mashery.com/v2/companies?companynames=*micro*&offset=25&appkey={APPKEY}

Parameter offset cannot be larger than 9,000,000,000,000,000,000.

Invalid request:

http://edgaronline.api.mashery.com/v2/companies?companynames=*micro*&offset=9000000000000000001&appkey={APPKEY}

Response:

400 Bad Request
{
   "Message": "Parameter 'offset' has invalid value. Parameter should contain only a valid integer value within the range of 0 - 9000000000000000000."
}

To output a large number of rows use the both limit and offset parameters.

Example:

http://edgaronline.api.mashery.com/v2/corefinancials/ann?primaryexchanges=OTCBB&numperiods=2&offset=100&limit=9999&appkey={APPKEY}

The call above will return all the rows starting from 101.

Threshold

Threshold is the technical limit that will generate a“400 Bad Request” error when the output, with filters applied, is greater than or equal to 1,000 records. "Limit" parameter is used if only threshold limit are met.

Threshold limits are applied to the all Core and Insider resources; there are two exceptions - Ownership-CurrentIssueHolders and Ownership-CurrentOwnerHoldings - which are not limited to the 1,000 row limit.

Example:

http://edgaronline.api.mashery.com/v2/corefinancials/ytd?fields=BalanceSheetConsolidated&activecompanies=false&deleted=false&appkey={APPKEY}

Response:

400 Bad Request
{
   "Message": "Please refine your search criteria as results exceed the maximum threshold for rows. Results limited to 1000 rows."
}

SortBy:

All resources support the sortby parameter as a filter to the request. Users can sort by any given requested field if they are entitled for the field.

http://edgaronline.api.mashery.com/v2/companies?companynames=*micro*&limit=10&offset=10&sortby=companyName asc&appkey={APPKEY}

Negation:

Negation defines "exclude” or “include" any additional field in the response.

Negation are defined by adding a ! in front of the fields parameter; if including any additional fields then just specify the fieldname without ! in the fields parameter. Please note that user must be entitled for the field if they are adding any fields in response.

Example:

To remove the CIK from the response:

http://edgaronline.api.mashery.com/v2/companies?fields=!cik&companynames=*micro*&appkey={APPKEY}

To display only website url in the response:

http://edgaronline.api.mashery.com/v2/companies?fields=websiteurl&companynames=*micro*&appkey={APPKEY}