IODA's Event API allows users to query for outage events detected by IODA. An outage event is an instance of a macroscopic Internet outage affecting the edge of the network. Each event has well-defined fields, such as the outage's start-time, duration and other fields, as defined in the Common Outage Data Format.
IODA detects outage events using three data sources—Internet Background Radiation (IBR), BGP, and active probing. For more information about the detection methodology see the Help page. Events are detected by IODA when there is a significant drop followed by a subsequent increase in the timeseries of an IODA data source for a group of addresses (such as addresses belonging to the same geographic region or Autonomous System).
IODA’s Event API has been designed to allow users to query for subsets of outage events that users are interested in. Instead of retrieving all outage events that IODA has ever detected, users will typically be interested in specific subsets of events. For instance, users may seek only the events that affect a specific country or Autonomous System, or events that were detected during specific periods. In fact, we highly recommend that users use the available filter parameters to limit the number of results that are returned by the API.
We describe different ways to retrieve various subset(s) of outage events using the IODA Event API below, but for a detailed technical description of the API endpoints, parameters and responses please refer to the auto-generated Swagger (OpenAPI) Documentation.
The Event API allows a user to specify the time range in which they are
interested, using the from and until parameters.
The response will
include events that were detected during the user-specified
time range (we discuss the set of returned events in further
detail, along with edge cases, below).
The from and until parameters should both be
provided in Unix Epoch seconds.
For example, the following GET request will return all events detected by IODA between 20:00:00 to 23:00:00 on June 26, 2019:
GET https://ioda.caida.org/ioda/data/events?from=1561579200&until=1561590000&human=true {
"type": "watchtower.events",
"error": null,
"queryParameters": {
...
},
"data": {
"events": [
{
"datasource": "bgp.v4.visibility_threshold.min_50%_ff_peer_asns.visible_slash24_cnt",
"location": "asn.62196",
"start": 1561579800,
"duration": 6300,
"uncertainty": null,
"status": 0,
"fraction": null,
"score": 5250,
"location_type": "asn",
"location_code": "62196",
"location_name": "AS62196 (Rayan Ravesh Sena Ltd)",
"overlaps_window": false
},
...
{
"datasource": "active.ping-slash24.team-1.up_slash24_cnt",
"location": "geo.netacuity.AS.IR",
"start": 1561579800,
"duration": 7800,
"uncertainty": null,
"status": 0,
"fraction": null,
"score": 6461.9668664082,
"location_type": "country",
"location_code": "IR",
"location_name": "Iran (Islamic Republic Of)",
"overlaps_window": false
},
...
{
"datasource": "bgp.v4.visibility_threshold.min_50%_ff_peer_asns.visible_slash24_cnt",
"location": "geo.netacuity.AS.IR",
"start": 1561579800,
"duration": 6300,
"uncertainty": null,
"status": 0,
"fraction": null,
"score": 4166.6918087193,
"location_type": "country",
"location_code": "IR",
"location_name": "Iran (Islamic Republic Of)",
"overlaps_window": false
},
...
]
}
}Since the Event API is constructed from the underlying Alert API, there are some edge-cases where the event API’s results can be counterintuitive.
The API works exactly as
expected for events that have both a start-time and end-time that
lie within the specified time range. For example, consider the
following GET request, which will return all events detected by
IODA between 20:00:00 to 23:00:00 on June 26, 2019 in Iran (we
discuss how to obtain events by specific geographic regions and
ASNs in more detail below):
GET https://ioda.caida.org/ioda/data/events?from=1561579200&until=1561590000&human=true&meta=country/IR {
"type": "watchtower.events",
"error": null,
"queryParameters": {
...
},
"data": {
"events": [
{
"datasource": "active.ping-slash24.team-1.up_slash24_cnt",
"location": "geo.netacuity.AS.IR",
"start": 1561579800,
"duration": 7800,
"uncertainty": null,
"status": 0,
"fraction": null,
"score": 6461.9668664082,
"location_type": "country",
"location_code": "IR",
"location_name": "Iran (Islamic Republic Of)",
"overlaps_window": false
},
{
"datasource": "bgp.v4.visibility_threshold.min_50%_ff_peer_asns.visible_slash24_cnt",
"location": "geo.netacuity.AS.IR",
"start": 1561579800,
"duration": 6300,
"uncertainty": null,
"status": 0,
"fraction": null,
"score": 4166.6918087193,
"location_type": "country",
"location_code": "IR",
"location_name": "Iran (Islamic Republic Of)",
"overlaps_window": false
},
{
"datasource": "bgp.v4.visibility_threshold.min_50%_ff_peer_asns.visible_slash24_cnt",
"location": "geo.netacuity.AS.IR",
"start": 1561586700,
"duration": 1500,
"uncertainty": null,
"status": 0,
"fraction": null,
"score": 28.015430036851,
"location_type": "country",
"location_code": "IR",
"location_name": "Iran (Islamic Republic Of)",
"overlaps_window": false
}
]
}
}start-times after
the from parameter and their end-times
before the until parameter.
Counterintuitive results can be returned when an event lies within the specified time-range but also lies partially outside. We describe the three different scenarios in which events can lie partially outside the specified time-range and the behavior of the API for each below.
When this scenario occurs, the API returns the event; however, its
duration is truncated (the event appears to end at the
specified until time).
Modifying the GET request to query for the events detected by IODA between 20:00:00 to 22:00:00 on June 26, 2019 in Iran, we see:
GET https://ioda.caida.org/ioda/data/events?from=1561579200&until=1561586400&human=true&meta=country/IR {
"type": "watchtower.events",
"error": null,
"queryParameters": {
...
},
"data": {
"events": [
{
"datasource": "bgp.v4.visibility_threshold.min_50%_ff_peer_asns.visible_slash24_cnt",
"location": "geo.netacuity.AS.IR",
"start": 1561579800,
"duration": 6300,
"uncertainty": null,
"status": 0,
"fraction": null,
"score": 4166.6918087193,
"location_type": "country",
"location_code": "IR",
"location_name": "Iran (Islamic Republic Of)",
"overlaps_window": false
},
{
"datasource": "active.ping-slash24.team-1.up_slash24_cnt",
"location": "geo.netacuity.AS.IR",
"start": 1561579800,
"duration": 6600,
"uncertainty": null,
"status": 0,
"fraction": null,
"score": 5467.81811773,
"location_type": "country",
"location_code": "IR",
"location_name": "Iran (Islamic Republic Of)",
"overlaps_window": true
}
]
}
}start-time within the specified interval are returned by this query;
however, the duration of
the event beginning at 1561579800 (20:10:00 on June 26, 2019)
has now been truncated to 6600 seconds whereas the duration of the
other event (whose end-time falls before the until parameter) remains unchanged. In addition,
the overlaps_window field has been set to "true" for
the former event, to indicate that its duration has been truncated.
When this scenario occurs, the API does not return the event.
Modifying the GET request to query for the events detected by IODA between 21:00:00 to 23:00:00 on June 26, 2019 in Iran, we see:
GET https://ioda.caida.org/ioda/data/events?from=1561582800&until=1561590000&human=true&meta=country/IR {
"type": "watchtower.events",
"error": null,
"queryParameters": {
...
},
"data": {
"events": [
{
{
"datasource": "bgp.v4.visibility_threshold.min_50%_ff_peer_asns.visible_slash24_cnt",
"location": "geo.netacuity.AS.IR",
"start": 1561586700,
"duration": 1500,
"uncertainty": null,
"status": 0,
"fraction": null,
"score": 28.015430036851,
"location_type": "country",
"location_code": "IR",
"location_name": "Iran (Islamic Republic Of)",
"overlaps_window": false
}
]
}
}until parameter since these events
started before the from parameter.
When this scenario occurs, the API does not return the event.
Modifying the GET request to query for the events detected by IODA between 21:00:00 to 22:00:00 on June 26, 2019 in Iran, we see:
GET https://ioda.caida.org/ioda/data/events?from=1561582800&until=1561586400&human=true&meta=country/IR{
"type": "watchtower.events",
"error": null,
"queryParameters": {
...
},
"data": {
"events": []
}
}
Users can specify the geographic region or Autonomous System they seek
using the meta parameter and the API will return the relevant subset
of events. Each event detected by IODA includes a meta field that indicates
the group of addresses that the event affects: the group may be addresses
geolocating to a country, addresses geolocating to a region within a country, or addresses
belonging to a specific Autonomous System. Users who would like to see only events affecting
Autonomous Systems can set meta=asn and the API will return all such events. Further, setting
meta=country/<country-code>, meta=region/<region-code>, meta=asn/<Autonomous-System-Number> allows users to view only the subset of
events affecting the user-specified group of addresses.
The API supports two levels of granularity for geographic regions: country and administrative regions within countries (like states in the U.S. or provinces in Canada).
To request events for all (any) countries, the meta parameter should be
set to country (i.e., meta=country).
To request events for a specific country, the meta parameter
should be set to country/<2-letter-ISO-country-code>. For example, meta=country/US.
For example, the following GET request will return events detected in the U.S. between 10:00:00 to 11:00:00 on Jan 10, 2019:
GET https://ioda.caida.org/ioda/data/events?from=1547114400&until=1547118000&human=true&meta=country/US{
"type": "watchtower.events",
"error": null,
"queryParameters": {
...
},
"data": {
"events": [
{
"datasource": "bgp.v4.visibility_threshold.min_50%_ff_peer_asns.visible_slash24_cnt",
"location": "geo.netacuity.NA.US",
"start": 1547116200,
"duration": 1800,
"uncertainty": null,
"status": 0,
"fraction": null,
"score": 44.485644345377,
"location_type": "country",
"location_code": "US",
"location_name": "United States",
"overlaps_window": true
}
]
}
}To request events for specific geographic regions, users need to know the identifier for the region that IODA uses internally. We plan to expose the ability to query for specific regions in a future version.
The API allows users to specify which Autonomous Systems they seek, also
using the meta parameter.
Similarly to country, events for all (any) ASNs can be retrieved by
setting the meta parameter to asn (meta=asn).
To request events for a specific Autonomous System,
the meta parameter should be set to asn/<Autonomous-System-Number>.
For example, meta=asn/3307.
For example, the following GET request will return events detected in AS 3307 between 10:00:00 to 11:00:00 on Jan 10, 2019::
GET https://ioda.caida.org/ioda/data/events?from=1547114400&until=1547118000&human=true&meta=asn/3307{
"type": "watchtower.events",
"error": null,
"queryParameters": {
...
},
"data": {
"events": [
{
"location": "asn.3307",
"start": 1547117700,
"duration": 300,
"uncertainty": null,
"status": 0,
"fraction": null,
"score": 500,
"location_type": "asn",
"location_code": "3307",
"location_name": "AS3307 (Broadnet AS)",
"overlaps_window": true
}
]
}
}