---

Overview

The CAIDA Spoofer Data API provides a public data interface to the publicly shareable data collected by the Spoofer service.

Data API URL

Users can request data via the URL: https://api.spoofer.caida.org/ whose home page provides information on endpoint syntax and data model.

Endpoints

• GET /sessions Retrieves the collection of Session resources
• GET /sessions/{id} Retrieves a Session resource.

Rules of Usage

These are the rules for the usage of the data API:

• CAIDA places no limit on the amount of requests, however, we ask that you send a message to spoofer-info at caida dot org if you plan to regularly do more than 1000 requests/day.
• The CAIDA Master Acceptable Use Agreement (AUA) terms and conditions apply.

Data Model

The data model contains a unique integer identifier for each session with a timestamp and parameters for read access, the IPv4 client address, the IPv6 client address, the country, NAT4 address, NAT6 address, and information about private and routed addresses. The API allows the user to query based on date, sessionid, or by Autonomous System Number (ASN). The API returns a paginated list of measurement sessions.

Try out the API in your browser

If you point your browser at https://api.spoofer.caida.org you will see the Spoofer API 1.0.0 documentation. To expand the documentation for each endpoint, click the GET buttons. Once expanded, each endpoint displays the example parameters with buttons to "Try it out." The try it out button provides a graphical interface that allows the user to build and execute queries to the Spoofer API and see the example responses.

Example Script

We offer an example script, implemented in PERL, that programmatically queries the Spoofer Data API.

The script takes command line arguments to query by date or sessionid with an optional Autonomous System Number (ASN). The script assumes the local system has the curl data transfer tool installed as well as the JSON::XS and Getopt::Long; PERL packages. At runtime, the script collects its command-line arguments and builds a query for the Spoofer Data API.

The API returns a list of sessions one page (30 lines) at a time. The example script decodes each line of JSON and prints the page numbers (to STDERR so as not to send redirected results output to file) preceding each page of results received.

The curl command makes use of the '-s' (silent) mode as well as '-X' switch to specify a custom GET command-line.

The following example execution of the dump-spoofer-api-after.pl script returns all public Spoofer measurement sessions after May 1, 2020. perl dump-spoofer-api-after.pl --date "1 May 2020"

The Spoofer Data API platform core provides native support for pagination in the collection results it returns. Each page contains 30 items per page by default. The code chunk below (lines 69-101 of the example script) displays the heart of the script, a while () loop, that handles the paginated results returned by the Spoofer Data API. The script determines the type of query and command arguments; either target sessionid, ASN, or time range and constructs the appropriate command-line to send to the Spoofer Data API. The while loop below processes the results returned by the GET request to the API as a collection of objects.

while(1)
{
    print STDERR "page $page
";
    my $obj;
    open(CURL, "$cmd |") or die "could not curl";
    while(<CURL>)
    {
        chomp;
        $obj = decode_json($_);
    }
    close CURL;
    last if(!defined($obj));
    foreach my $member (@{$obj->{"hydra:member"}})
    {
        my $str = encode_json($member);
        print "$str
";
    }
    if(defined($obj->{"hydra:view"}) &&
        defined($obj->{"hydra:view"}{"hydra:next"}))
    {
        my $next = $obj->{"hydra:view"}{"hydra:next"};
        $cmd = "curl -s -X GET \"$api$next\" -H \"$accept\"";
    }
    else
    {
        last;
    }
    $page++;
}

Example response records:

{"@id":"/sessions/887477","@type":"Session","asn4":"12222","asn6":"12222","client4":"88.221.209.0/24","client6":"2001:4878:8200::/40","country":"pol","nat4":true,"nat6":false,"privatespoof":"rewritten","privatespoof6":"received","routedspoof":"rewritten","routedspoof6":"received","session":887477,"timestamp":"2020-05-01T00:00:12+00:00"}
{"@id":"/sessions/887480","@type":"Session","asn4":"2485","asn6":"3215","client4":"192.134.4.0/24","client6":"2a01:cb04:100::/40","country":"fra","nat4":true,"nat6":false,"privatespoof":"blocked","privatespoof6":"blocked","routedspoof":"blocked","routedspoof6":"blocked","session":887480,"timestamp":"2020-05-01T00:08:24+00:00"}
{"@id":"/sessions/887481","@type":"Session","asn4":"32780","asn6":null,"client4":"196.52.2.0/24","client6":null,"country":"usa","nat4":true,"nat6":null,"privatespoof":"unknown","privatespoof6":null,"routedspoof":"unknown","routedspoof6":null,"session":887481,"timestamp":"2020-05-01T00:10:10+00:00"}
{"@id":"/sessions/887482","@type":"Session","asn4":"33915","asn6":"33915","client4":"83.85.71.0/24","client6":"2001:1c00:d00::/40","country":"nld","nat4":true,"nat6":false,"privatespoof":"blocked","privatespoof6":"blocked","routedspoof":"blocked","routedspoof6":"blocked","session":887482,"timestamp":"2020-05-01T00:15:50+00:00"}

---