Simple Best API

The Simple Best API allows to fetch a single result, the best matching one. You can just pass the asset value and not a full ONYPHE Query Language search. Only a few categories are useful in this context, which are the following:

/simple/geoloc/best/{IP}: you have to give a valid IPv4 or IPv6 address (example: 8.8.8.8);
/simple/inetnum/best/{IP}: you have to give a valid IPv4 or IPv6 address (example: 8.8.8.8);
/simple/whois/best/{IP}: you have to give a valid IPv4 or IPv6 address (example: 8.8.8.8).
/simple/threatlist/best/{IP}: you have to give a valid IPv4 or IPv6 address (example: 8.8.8.8);

Simple Geoloc, Inetnum & Whois Best endpoints will return the geolocation of the given address, and the smallest network (subnet field) will be the best match.

Simple Threatlist Best will return a result if an entry has been found in threatlist category within the last 48-hours. The idea behind this endpoint is that you want to know if an address has been considered as malicious in the past few days only. IP addresses are sometimes cleaned-up and do not pose a threat anymore.

Using curl

You can use curl in the following way to call the Simple Best API:

curl -H 'Content-Type: application/json' -H 'Authorization: bearer YOUR_APIKEY' -XGET 'https://www.onyphe.io/api/v2/simple/whois/best/8.8.8.8'

Output:

{
  "count": 1,
  "error": 0,
  "max_page": 1,
  "myip": "<redacted>",
  "page": 1,
  "page_size": 1,
  "results": [
    {
      "@category": "whois",
      "@timestamp": "2023-02-20T22:30:45.000Z",
      [..]
  ],
  "status": "ok",
  "text": "Success",
  "took": "0.010",
  "total": 20
}

Using curl against Unrated API endpoint

If you want to query against the Unrated API endpoint, you have to pass the API key as an HTTP parameter as the Authorization header will be used to store Basic authentication credentials based on your login email address and your API key as a password:

LOGIN=`echo -n YOUR_LOGIN_EMAIL | sed 's/@/_/g'`
PASS=YOUR_APIKEY
BASIC=`echo -n $LOGIN:$PASS | base64 -w 0`
curl -H 'Content-Type: application/json' -H "Authorization: basic $BASIC" -XGET 'https://www.onyphe.io/unrated/api/v2/simple/whois/best/8.8.8.8?k=YOUR_APIKEY'