Community API Documentation

The community API v1 has three endpoints available enabling search on domains, TLDs and IANA registrars (via ID).

Authenticate

The first step is to authenticate to the API

https://account-api.icann.org/api/authenticate

Posting the following JSON:

{
    "username":"icann account username",
    "password":"your icann account password"
}

E.g. using curl:

curl -H "Content-Type: application/json" --data '{"username": "[YOUR_USER_NAME]", "password": "[YOUR_PASSWORD]"}' https://account-api.icann.org/api/authenticate

The response to this should contain an "accessToken", for example:

{"accessToken":"eyJra6Q…ijTf86e","message":"Authentication Successful"}

This token will be valid for 24 hours and needs to be used in future calls in a header field "Authorization" along with your username, so with curl an API call would look like:

curl -H "Content-Type: application/json" -H "Authorization: Bearer [TOKEN]" "[REQUEST]"

where:
REQUEST = the URL defining the search to be executed, as specified below.

TLD Search

There are two basic options for the TLD search endpoint:

End point with gTLD specified

https://domainmetrica.icann.org/v1/domainmetrica/tld?tld=<TLD>&startDate=<STARTDATE>&endDate=<ENDDATE>

where:
TLD = gTLD to be searched on

STARTDATE = Date to search from, format 'YYYY-MM-DD' (default 24 hours ago)
ENDDATE = Date to search to (default now)

Example Output

{"example_tld":
    [
        {"date": "2024-01-01", "zone_size": 30000, "reported_abuse_total": 58, "phishing": 50, "malware": 12, "botnet c&c": 5},
        {"date": "2024-01-02", "zone_size": 30000, "reported_abuse_total": 60, "phishing": 55, "malware": 8, "botnet c&c": 5},
        {"date": "2024-01-03", "zone_size": 30000, "reported_abuse_total": 72, "phishing": 60, "malware": 11, "botnet c&c": 5},
        {"date": "2024-01-04", "zone_size": 30000, "reported_abuse_total": 55, "phishing": 52, "malware": 10, "botnet c&c": 4}
    ]
}

where:
"date" is in the same 'YYYY-MM-DD' format as above
"zone_size" is the number of delegations seen on that date
"reported_abuse_total" is the number of unique domains reported on that date, covering phishing, malware and botnet C&C reports
"phishing", "malware" and "botnet c&c" give the counts of unique domains reported for those categories. Note that the sum of these may not be the same as the abuse total due to domains being reported in multiple categories.

End point no TLD

This will return aggregate data for all gTLDs

https://domainmetrica.icann.org/v1/domainmetrica/tld?startDate=<STARTDATE>&endDate=<ENDDATE>

Example Output

{"all_tlds":
    [
        {"date": "2024-01-01", "zone_size": 30000, "reported_abuse_total": 58, "phishing": 50, "malware": 12, "botnet c&c": 5},
        {"date": "2024-01-02", "zone_size": 30000, "reported_abuse_total": 60, "phishing": 55, "malware": 8, "botnet c&c": 5},
        {"date": "2024-01-03", "zone_size": 30000, "reported_abuse_total": 72, "phishing": 60, "malware": 11, "botnet c&c": 5},
        {"date": "2024-01-04", "zone_size": 30000, "reported_abuse_total": 55, "phishing": 52, "malware": 10, "botnet c&c": 4}
    ]
}

IANA Registrar Search

There are two basic options for the TLD search endpoint:

End point with IANA ID specified

https://domainmetrica.icann.org/v1/domainmetrica/registrar?ianaID=<IANAID>&startDate=<STARTDATE>&endDate=<ENDDATE>

where:
IANAID = IANA registrar ID to be searched on

STARTDATE = Date to search from, format 'YYYY-MM-DD' (default 24 hours ago)
ENDDATE = Date to search to (default now)

Example Output

{"example_IANAID":
    [
        {"date": "2024-01-01", "gTLD_portfolio_size": 30000, "reported_abuse_total": 58, "phishing": 50, "malware": 12, "botnet c&c": 5},
        {"date": "2024-01-02", "gTLD_portfolio_size": 30000, "reported_abuse_total": 60, "phishing": 55, "malware": 8, "botnet c&c": 5},
        {"date": "2024-01-03", "gTLD_portfolio_size": 30000, "reported_abuse_total": 72, "phishing": 60, "malware": 11, "botnet c&c": 5},
        {"date": "2024-01-04", "gTLD_portfolio_size": 30000, "reported_abuse_total": 55, "phishing": 52, "malware": 10, "botnet c&c": 4}
    ]
}

Where the fields have the same meaning as for TLD Searches along with:
"gTLD_portfolio_size" is the number of registrations that we can link to the registrar via gTLD reporting data

End point no IANA ID

This will return aggregate data for all domains where we can match an IANA ID

https://domainmetrica.icann.org/v1/domainmetrica/registrar?startDate=<STARTDATE>&endDate=<ENDDATE>

Example Output

{"all_IANA_IDs":
    [
        {"date": "2024-01-01", "gTLD_portfolio_size": 30000, "reported_abuse_total": 58, "phishing": 50, "malware": 12, "botnet c&c": 5},
        {"date": "2024-01-02", "gTLD_portfolio_size": 30000, "reported_abuse_total": 60, "phishing": 55, "malware": 8, "botnet c&c": 5},
        {"date": "2024-01-03", "gTLD_portfolio_size": 30000, "reported_abuse_total": 72, "phishing": 60, "malware": 11, "botnet c&c": 5},
        {"date": "2024-01-04", "gTLD_portfolio_size": 30000, "reported_abuse_total": 55, "phishing": 52, "malware": 10, "botnet c&c": 4}
    ]
}

Domain Search

This endpoint returns any RBL data seen and the Tranco ranking (if in top million).

Basic search

https://domainmetrica.icann.org/v1/domainmetrica/domain?domain=<DOMAIN>&startDate=<STARTDATE>&endDate=<ENDDATE>

where:
DOMAIN = fully qualified domain name (FQDN) to be searched on
STARTDATE = Date to search from, format 'YYYY-MM-DD'  (default 24 hours ago)
ENDDATE = Date to search to (default now)

Further options

We can also filter by reported abuse type and/or RBL name:

https://domainmetrica.icann.org/v1/domainmetrica/domain?domain=<DOMAIN>&RBL_name=<RBL>&reported_abuse_type=<TYPE>&startDate=<STARTDATE>&endDate=<ENDDATE>

Where:
RBL = RBL name (possible values: 'surbl','spamhaus','phishtank','apwg','wmcphishfeed','urlhaus')
TYPE = reported abuse type (possible values: 'Phishing','Malware','Botnet%20C%26C')

Example Outputs
(1) Domain Name with reported abuse + Tranco ranking

{
    "example.com": {
        "reported_abuse": [
            {"date": "2024-01-01", "RBL_name": "surbl", "reported_abuse_type": "phishing", "url_count": 3},
            {"date": "2024-01-01", "RBL_name": "spamhaus", "reported_abuse_type": "phishing", "url_count": 3},
            {"date": "2024-01-02", "RBL_name": "phishtank", "reported_abuse_type": "phishing", "url_count": 3}
        ],
        "tranco_ranking": [
            {"date": "2024-01-01", "rank": 45},
            {"date": "2024-01-02", "rank": 47}
        ]
    }
}

Where:
"RBL_name" is the reputation block list which contained the domain
"reported_abuse_type" is the type of abuse the domain was included under (note, as in the example above a domain can be included on multiple RBLs and for multiple abuse types)
"url_count" is the number of unique entries on the RBL for the specific reported abuse type.
"rank" is the position reported in the TRANCO ranking data on that date

(2) response with no data has empty arrays, e.g. no reported abuse

{
    "example.com": {
        "reported_abuse": [],
        "tranco_ranking": [
            {"date": "2024-01-01", "rank": 45},
            {"date": "2024-01-02", "rank": 47}
        ]
    }
}

Potential Error Codes

400: 'Bad Request'
The request was in some way malformed, this might be the date formatting for example. More detail will be returned in the content of the response.

401: 'Not Authorised'
This indicates a problem with authentication. Possibly a token has expired and requires renewal.

429: 'Too Many Requests'
This error code will be seen when the users daily quota has been exceeded. Limits are reset at midnight UTC.