Queried Quickstart
Query Cyber Risk Analytics Data as Your Needs Dictate

How it Works

Query the SurfWatch Analytics API for cyber data when you need it and use filters to ensure you get only the data you want. The queries use industry standard protocols.

On a more technical level, HTTP GET requests are sent to our REST endpoint. The response body is a JSON formatted result. Query parameters and request headers control query behavior - such as gzip compression of the HTTP Response.

It's really easy to setup! Using the code samples below, you can query our endpoints in 5 minutes.

Queried

Code and Getting Started

Configure Your Subscription

To query our data, you'll need authentication tokens

  1. If you received it haven't already, you'll need API access. Learn more at our API page.
  2. Once you've got API access, you can go to My API Profile.
  3. To ensure security, we do not store your keys in our system. You will need to click the 'Generate New Key' button. If you ever lose the keys, you can regenerate them here.
  4. Dive into the code below.

Choose a programming language below for code examples

These steps get your client ready, write the code, and query the SurfWatch Analytics REST API.

A Java client using Jersey

Setup Your Environment

Before you run the code, make sure Maven is installed using the maven-in-five-minutes instructions.
If you are unfamiliar with Maven, you can find documentation at maven.apache.org to get you started.

Source Code

If you'd prefer, you can clone the following code from GitHub and skip to the 'Run the Code' section.

Code

In your workspace, create a folder named surfwatch-rest-client. Open a terminal window and change directories to this folder.

Run the following:

mvn archetype:generate -DgroupId=com.surfwatchlabs.api -DartifactId=rest.client.examples -Dversion=3.0.0 -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

This produces the following Maven project structure, with rest.client.examples as the project root:

rest.client.examples
|-- pom.xml
|-- src
|  `-- main
|    `-- java
|     `-- com
|       `-- surfwatchlabs
|         `-- api
|           `-- App.java
|
|`-- test
|   `-- java
|     `-- com
|       `-- surfwatchlabs
|         `-- api
|           `-- AppTest.java

Copy the following to src/main/java/com/surfwatchlabs/api/FeedRiskScoreClient.java :

Replace the contents of pom.xml with:

Run the Code

The easiest way to execute the code is to run the code from an IDE that understands maven projects (most Java IDEs nowadays). Other options would be to compile the class and set your classpath to manually include the maven dependencies, or to make a 'fat' jar that contains all dependencies. Use an IDE to run it, trust us ;)

This will submit a HTTP GET request to SurfWatch Analytics REST API. The code will then handle and print out the results.

If an error results, please make sure that you have satisfied the necessary dependencies for both Ruby and HTTP Client. Remember, you also need to have an API plan in order to acquire an Application ID and Application Key from My API Profile.

A Ruby client using REST Client

Setup Your Environment

Before you run the code, you will need to setup your environment.

  1. Install Ruby, per these instructions https://www.ruby-lang.org/en/installation/
  2. Install the REST Client gem.

Source Code

If you'd prefer, you can clone the following code from GitHub and skip to the 'Run the Code' section.

Code

Create a file called feed_risk_score_client.rb with the content

require 'rest_client'
require 'json'

url = 'https://www.surfwatchlabs.com:443/api/v3/feedRiskScores'

# Get feed risk scores from yesterday
header = {
  'content-type' => 'application/json',
  'app-key' => ENV['SURFWATCH_ANALYTICS_APP_KEY'],
  'app-id' => ENV['SURFWATCH_ANALYTICS_APP_ID'],
  :params => { 'yesterday' => 'true' }
}

puts
puts "Request : GET, url : #{url}"

response = RestClient.get(url, header)
puts
puts "Response from /yesterday resource : #{response}"

results = JSON.parse(response)
puts
puts "Found #{results.size} feed risk scores from yesterday."
puts

results.each do |irs|
  if irs['feed_risk'] > 50
    str_bldr = "Found a feed score over 50 : "
    str_bldr << "feed="
    str_bldr << irs['feed_description']
    str_bldr << ", risk_score="
    str_bldr << irs['feed_risk'].to_s
    str_bldr << ", analytic_day="
    str_bldr << irs['analytic_day'].to_s
    puts str_bldr
  end
end

puts
puts "Well that was fun!"
puts

Run the Code

To run the code, open a new terminal window and change directories to the location of the industry_risk_score_client.rb file. Set your app-id and app-key to environment variables, then simply type ruby feed_risk_score_client.rb

This will submit a HTTP GET request to SurfWatch Analytics REST API. The code will then handle and print out the results.

If an error results, please make sure that you have satisfied the necessary dependencies for both Ruby and HTTP Client. Remember, you also need to have an API plan in order to acquire an Application ID and Application Key from My API Profile.