Getting started with the API
About the Enigma Public API
The Enigma Public API (“application programming interface”) lets you access datasets and metadata programmatically, in ways that aren’t possible through the web application. Use of the API is available to individuals for non-commercial use subject to Enigma’s Terms of Service and the following limitations:
- 50,000 data API calls monthly
- 50,000 metadata API calls monthly
- 80 export API calls monthly
To increase your API allowance, send an email to firstname.lastname@example.org. For commercial use, see https://www.enigma.com/data or contact us at email@example.com and a member of our sales team will help you find the right solution for your needs.
The Enigma Public API is fully documented in the Enigma API Reference. For those who are new to HTTP APIs, below is a quick tutorial to get you started.
Executing your first API call
You may have noticed the API button at the top right of the Enigma Public Data Viewer. When you’re signed in (see Creating an account), this button executes an API call to get the metadata for the current data snapshot as well as the first 25 data records, and displays the resulting information in your browser.
If you look in the browser address bar, you’ll see the URL that generated the data. It will look something like this:
This URL references the API’s
/snapshots/ endpoint, which returns the information for the snapshot with the specified ID.
Using a REST client
The Enigma Public API is a REST API. If you’re new to REST APIs, a REST client is a good way to explore the API’s capabilities. In this tutorial, we’ll show you how to begin using the Enigma Public API using Postman, one of the most popular REST clients.
Postman is available as a standalone application for Windows PCs and Macs, and also as a Chrome extension. Download and install the appropriate version from https://www.getpostman.com/.
Once you’ve installed Postman on your computer, you can use it to access the Enigma Public API.
To execute an API call:
- In Enigma Public, make sure you’re signed in and then open any dataset in the Data Viewer. You must be signed in to use the API function.
- Click the API button at the top right of the screen. The resulting page is displayed in a new browser window.
- In the browser address bar, select the entire address and copy it to the clipboard.
- Start Postman and paste the URL into the “Enter request URL” field.
- Click Send.
When you click Send, depending on the API call, you may receive the following response:
This is because the Enigma Public API expects an authorization code, or API key (see Authentication).
To get your API key:
- In Enigma Public, click your initials at the top right of the window and choose Settings.
- Locate your API key at the bottom of the Settings window.
- Copy your API key to the clipboard.
To execute the API call again with your API key:
- In Postman, click the Headers tab.
- In the “New key” field, type
- In the “Value” field, type
Bearer:and paste in your API key, as shown below.
- Click Send to execute the call again.
This time, you should see a response like the one below (the same data you saw when you clicked the API button in the Data Viewer).
Congratulations, you just executed your first API call from Postman!
Understanding what just happened
The Enigma Public API defines a set of endpoints you can call to get back different kinds of information. In the first example, you used the
GET method (the default action) on the
/snapshots/ endpoint to get information about a specific snapshot (the one identified using the snapshot ID).
|Base URL||Endpoint name||Snapshot ID|
In order to execute the call, you included your API key using the
Authorization header. When the server at https://public.enigma.com/api received the request, it confirmed that the API key was a valid key and then returned the requested data in JSON format (JSON is the default response format).
If you look at the API Reference, you’ll see the API has other endpoints:
For each endpoint, you’ll see the parameters it supports and examples of how to use it. There are four parameter types:
- Path parameters: These appear within the endpoint path. In the example above, the snapshot ID is a path parameter.
- Query parameters: These appear after a question mark following the path. In the example above,
row_limitis a query parameter.
- Request body parameters: These are used when sending information to the API (not used with
- Header parameters: These are included in the request header. In the example above, you used the Authorization header to send your API key.
Next, you’ll use a different query parameter to send a search term to the API.
Searching through the API
/collections/ endpoint has a query parameter called
query that lets you send a search string to the API. The API searches the metadata for all collections, and returns information about any matching collections.
Keep in mind that you’re searching the collection metadata, and not any of the data associated with the collection. To search within datasets, you’ll need to use the
Here’s an example of an API call to search the collection metadata for the words “federal” and “reserve.” Notice that you can’t include space characters in the query string, so you must use the URL-encoded ASCII equivalent (%20) instead.
|To search for the phrase “federal reserve,” you must use quotes with the backslash escape character, for example,
Try pasting the URL above into Postman’s “Enter request URL” field and click Send.
The API returns a lot more information than is shown here. If you scroll through the response you’ll see that for every collection that includes the words “federal” and “reserve” the response includes:
- Information about the collection (creation date, description, etc.)
- Information about its ancestors (collections that precede it in the collection hierarchy)
- Offset values a client application can use to highlight the search terms
Additionally, if your search results in more than 20 hits, you’ll receive only the first 20, unless you specify a different value using the Range header. For more information, see Pagination in the API Reference.
cURL is a command line utility that lets you execute HTP requests and is a standard used in most HTTP API documentation, as it provides a compact notation for defining HTTP requests with parameter types (path, query, header, and body) that is not specific to a particular programming language or client application.
cURL is installed on most Macs by default. To confirm that it’s installed on your Mac:
- Open a Terminal window.
curl -Vand press Enter. You should see something like this:
$ curl -V curl 7.51.0 (x86_64-apple-darwin16.0) libcurl/7.51.0 SecureTransport zlib/1.2.8 Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtsp smb smbs smtp smtps telnet tftp Features: AsynchDNS IPv6 Largefile GSS-API Kerberos SPNEGO NTLM NTLM_WB SSL libz UnixSockets
If you have a Windows PC, you’ll need to install a version of cURL. cURL is included with Git for Windows, so if you already have that you can open a Git Bash window and execute curl commands from there. Otherwise, search for “curl windows” and find a version of cURL that’s compatible with your Windows version. Once installed, use the
curl -V command shown above to confirm cURL is working.
With cURL installed, execute the API call from first example as shown below:
$ curl https://public.enigma.com/api/snapshots/8b69342e-75dd-44e5-804b-528fe497f1c9 -H "Authorization: Bearer <APIKEY>
Notice the use of
-H to indicate a header parameter. Replace
<APIKEY> with the key you used earlier. The command should return the same JSON you saw when you executed the command from Postman.
You can execute the API call for the second example as shown below:
$ curl https://public.enigma.com/api/collections/?query=federal%20reserve -H "Authorization: Bearer <APIKEY>"
Again, the command should return the same JSON you saw earlier.
The examples you went through in this section using Postman and cURL should provide you with a basic understanding of how to use the Enigma Public API. Refer to the API Reference for complete information on how to access Enigma Public through the API.