badips.com Follow @badipscom

www.badips.com API documentation

Tweet

GET /add/<category>/<IP>

/add is used to report an IP.

sample request


    http://www.badips.com/add/ssh/1.2.3.4
    

sample answer


      {
        "err":"",
        "suc":"added 1.2.3.4 in category ssh by <your IP>"
      }
    

GET /get/categories

/get/categories is used to retrieve all valid categories.

sample request


    http://www.badips.com/get/categories
    

sample answer


     {
       "categories": [
         {
           "Name": "ssh",
           "Desc": "SSH bruteforce login attacks and other ssh related attacks"
         }
       ]
     }
    

GET /get/stats/count

/get/stats/count returns the number of IPs in our database.

sample request


    http://www.badips.com/get/stats/count
    

sample answer


    {
      "count":236
    }
    

additional options

  • ?format=
    • json
    • plain
  • ?category=
    • <category>
  • ?key=
    • <key>

GET /get/stats/countbycountry

/get/stats/countbycountry returns the number of IPs in our database by country.

sample request


    http://www.badips.com/get/stats/countbycountry
    

sample answer


    {
      "countbycountry":[
        "CN":92,
        "US":22,
        "FR":12,
        "KR":10,
        [...]
        }
      ]
    }
    

additional options

  • ?format=
    • json
    • plain
  • ?category=
    • <category>
  • ?key=
    • <key>

GET /get/stats/countbycategory

/get/stats/countbycategory returns the number of IPs in our database by category.

sample request


    http://www.badips.com/get/stats/countbycategory
    

If you'd like to see a breakdown for a parent category, enter query whit ?category= :


    http://www.badips.com/get/stats/countbycategory?category=http
    

sample answer


    {
      "countbycategory": [
      {
        "dovecot-pop3imap": 13207
      },
      {
        "ssh": 8292
      },
      {
        "postfix": 3159
      },
    [...]
    }
    

additional options

  • ?format=
    • json
    • plain
  • ?category=
    • <category>
  • ?key=
    • <key>
  • ?age=
    • e.g. 2w , 1d, 12h

GET /get/stats/countbyopenport

/get/stats/countbyopenport returns the number of IPs in our database which have defined ports open.

sample request


    http://www.badips.com/get/stats/countbyopenport?port=443
    

sample answer


    {
          "port 443 closed": 216,
          "port 443 open": 39
    }
    

additional options

  • ?port=
    • 22
    • 80
    • 443
    • 3389
  • ?format=
    • json
    • plain
  • ?category=
    • <category>
  • ?key=
    • <key>

GET /get/list/<category>/<score>

/get/list/ returns a list of IPs based on your selections.

sample request


    http://www.badips.com/get/list/ssh/0
    

sample answer


    <IP>
    <IP>
    <IP>
    <IP>
    <IP>
    <IP>
    [...]
    

additional options

  • ?format=
    • ipset
    • plain
  • ?category=
    • <category>
  • ?key=
    • <key>

GET /get/info/<IP>

/get/info/<IP> returns information on the given IP.

sample request


    http://www.badips.com/get/info/61.160.212.66
    

sample answer (listed IP)


    {
      "ReporterCount": {
        "sum": 7,
        "ssh": 7
      },
      "Categories": [
        "ssh"
      ],
      "Score": {
        "ssh": 5
      },
      "LastReport": {
        "ssh": 1389590320
      },
      "Whois": {
        "descr": [
          "CHINANET jiangsu province network",
          "China Telecom",
          "A12,Xin-Jie-Kou-Wai Street",
          "Beijing 100088",
          "CHINANET jiangsu province network"
        ],
        "inetnum": "61.160.0.0 - 61.160.255.255",
        "netname": "CHINANET-JS",
        "country": "CN"
      },
      "CountryCode": "CN",
      "rDNS": null,
      "suc": "IP 61.160.212.66 is listed on badips.com!",
      "Listed": true
    }
    

sample answer (IP not listed)


    {
        "suc": "IP 14.37.91.32 is not listed on badips.com!",
        "Listed": false
    }
    

Two fields are always* returned: "Listed" and "suc", "suc" is a bit more verbose while "Listed" is a bool. You can check "Listed" if you want to know wheter an IP is listed on badips.com or not.

*If you formulate an invalid request (e.g. an invalid IP format) you get a 400 error and "err" is set to inform you about the problem.

GET /get/country/<country>

/get/country/ returns a list of networks within the given country.

sample request


    http://www.badips.com/get/country/nl
    

sample answer


    <IP>
    <IP>
    <IP>
    <IP>
    <IP>
    <IP>
    [...]
    

additional options

  • ?format=
    • ipset
    • plain

GET /get/key

/get/key/ returns a unique key that is associated to your IP. This key can then later be used to query the website or API and retrieve personalised content. This can only be done from a reporting IP.

sample request


    http://www.badips.com/get/key
    

sample answer


    {
      "err":"",
      "suc":"new key 65bedf87249c427b0cb461687d25f7ac5d493540 has been set.",
      "key":"65bedf87249c427b0cb461687d25f7ac5d493540"
    }
    

additional options

  • ?force
  • set a new key, even if you already have one.

GET /set/key/<key>

/set/key/ adds the IP of the requester to a key. This can only be done from a reporting IP. Before you can set a key, you have to get one (see get/key above).

sample request


    http://www.badips.com/set/key/<key>
    

sample answer


    {
      "err":"",
      "suc":"new key 65bedf87249c427b0cb461687d25f7ac5d493540 has been set.",
      "key":"65bedf87249c427b0cb461687d25f7ac5d493540"
    }
    

additional options

  • ?force
  • set a new key, even if you already have one.

Error Handling

If your request produces an error, it will return HTTP status code 400 and represented in the returned JSON. Generally you can check if err object is empty. See sample request and sample answers.

sample request - no error


    http://www.badips.com/add/ssh/1.2.3.4
    

sample answer - no error


      {
        "err":"",
        "suc":"added 1.2.3.4 in category ssh by <your IP>"
      }
    

sample request - with error


    http://www.badips.com/add/ssh/10.0.0.1
    

sample answer - with error


    {
      "err":"IP is invalid (malformed or private).",
      "suc":""
    }