API Reference

client module

This module contains the class Client that implements all the logic of the client to connect to the API services of Apility.io.

All the methods return an Object that encapsulates the HTTP response status code, the error (if any), and the collection of objects needed.

class apilityio.client.Client(api_key=None, protocol='https', host='api.apility.net')

Create the web service client to access the API. This class implements all the logic of the client to connect to the API services of Apility.io.

Keyword Arguments:
  • api_key: A string containing your Apility.io API Key.
  • protocol: A string containing the protocol to connect to the API. Protocols allowed HTTP and HTTPS. Default protocol is HTTPS.
  • host: A string containing the FQDN of the host runnign the API.
Raises:
ApilityioValueError():: If the provided arguments cannot connect to the API Service.
GetConnectionData()

Return connection data used, the API KEY (if any), the protocol (http or https) and the hostname (api.apility.net by default).

Returns:
  • api_key: a string representing the Apility.io API KEY
  • protocol: a string representing the connection protocol http or https.
  • host: a string representing the FQDN where the Apility.io API is listening.
CheckIP(ip_address)

Check the IP address belongs to any list of the blacklist databases of Apility.io. It also returns the blacklists where the IP address was found.

Arguments:
  • ip_address: A string containing the IP address to check.
Returns:
  • BadIPResponse(): an object containing the HTTP status code response, the error (if any) and the list of blacklists where the IP address was found. A 404 HTTP response means that the IP address was not found in any blacklists. A 200 HTTP response means that the IP address was found in one or more blacklists and the developer can check the lists in the blacklists.
Raises:
CheckBatchIP(ip_addresses)

Check if a list of IP addresses belong to any list of the blacklist databases of Apility.io. It also returns the blacklists where the IP addresses were found.

Arguments:
  • ip_addresses: A list composed of strings containing the IP addresses to check.
Returns:
  • BadBatchIPResponse(): an object containing the HTTP status code response, the error (if any) and the list of blacklists where the IP addresses were found. For each IP address there is a list containing the blacklists where the IP was found. If the IP was not found in any blackllist then the list is empty.
Raises:
GetGeoIP(ip_address)

Get the IP address geo-location information.

Arguments:
  • ip_address: A string containing the IP address to geo-locate.
Returns:
  • GeoIPResponse(): an object containing the HTTP status code response, the error (if any) and the object containing the geo location properties of the IP address.
Raises:
GetGeoBatchIP(ip_addresses)

Get the gelocation information of a list of ip addresses passed as argument.

Arguments:
  • ip_addresses: A list of strings containing the IP addresses to geo-locate.
Returns:
  • GeoBatchIPResponse(): an object containing the HTTP status code response, the error (if any) and a list of objects containing the geo location properties of the IP addresses.
Raises:
CheckDomain(domain)

Check the Domain and its MX and NS records belong to any list of the blacklist databases of Apility.io. It returns the scoring and blacklists where the Domain info was found.

Arguments:
  • domain: A string containing the domain to check.
Returns:
  • BadDomainResponse(): an object containing the HTTP status code response, the error (if any) and the scoring and lists of blacklists where the Domain, MX and NS records were found. A 200 HTTP response means that the Domain, MX or NS records were found in one or more blacklists and the developer can check the scoring and the blacklists.
Raises:
CheckBatchDomain(domains)

Check if a list of Domain and its MX and NS records belong to any list of the blacklist databases of Apility.io. It returns a list of the scoring and blacklists where the Domains info were found.

Arguments:
  • domains: A list composed of strings containing the domains to check.
Returns:
  • BadBatchDomainResponse(): an object containing the HTTP status code response, the error (if any) and the list of blacklists where the IP addresses were found. Also the list of domains pairing the scoring and lists of blacklists where the Domain, MX and NS records were found.
Raises:
CheckEmail(email)

Check the Email including all tests performed to the Domain plus a full SMTP test on the remote server. It returns the global scoring of the Email and each scoring per test performed.

Arguments:
  • email: A string containing the email to check.
Returns:
  • BadEmailResponse(): an object containing the HTTP status code response, the error (if any) and the scoring and lists of blacklists where the Emal, SMTP server, MX and NS records were found. A 200 HTTP response means that the Domain, SMTP Server, MX or NS records were found in one or more blacklists and the developer can check the scoring and the blacklists.
Raises:
CheckBatchEmail(emails)

Check if a list of Emails including all tests performed to the Domain plus a full SMTP test on the remote server. It returns the global scoring of each Email and each scoring per test performed.

Arguments:
  • emails: A list composed of strings containing the emails to check.
Returns:
  • BadBatchEmailResponse(): an object containing the HTTP status code response, the error (if any). Also the list of emails pairing the scoring and lists of blacklists where the Emails, tests and domains and MX and NS records were found.
Raises:
GetASbyIP(ip_address)

Get the Autonomous System information of a given IP address.

Arguments:
  • ip_address: A string containing the IP address to obtain information of its Autonomous System.
Returns:
  • ASResponse(): an object containing the HTTP status code response, the error (if any) and the object containing the Autonomous System properties of the IP address.
Raises:
GetASbyNum(asnum)

Get the Autonomous System information by its number (ASN).

Arguments:
  • asnum: An integer containing the ASN to obtain information of.
Returns:
  • ASResponse(): an object containing the HTTP status code response, the error (if any) and the object containing the Autonomous System properties.
Raises:
GetASBatchByIP(ip_addresses)

Get the Autonomous System information of a list of ip addresses passed as argument.

Arguments:
  • ip_addresses: A list of strings containing the IP addresses to get AS data.
Returns:
  • ASBatchIPResponse(): an object containing the HTTP status code response, the error (if any) and a list of objects containing the Autonomous System properties of the IP addresses.
Raises:
GetASBatchByNum(as_numbers)

Get the Autonomous System information of a list of AS numbers passed as argument.

Arguments:
  • as_numbers: A list of integers containing the AS numbers to get AS data.
Returns:
  • ASBatchIPResponse(): an object containing the HTTP status code response, the error (if any) and a list of objects containing the Autonomous System properties of the AS numbers.
Raises:
GetWhoisIP(ip_address)

Get the WHOIS information of a given IP address.

Arguments:
  • ip_address: A string containing the IP address to obtain information of its WHOIS database.
Returns:
  • WhoisIPResponse(): an object containing the HTTP status code response, the error (if any) and the object containing the WHOIS properties of the IP address.
Raises:
GetHistoryIP(ip_address, timestamp=None, items=5, page=1)

Get the list of transactions of a given IP address in our database. For experts who wish to know the historical activity of the given IP address in our database.

Arguments:
  • ip_address: A string containing the IP address to obtain the historical information.
  • page: (Optional) An integer starting with 1 to paginate the results of the query.
  • items: (Optional) An integer with the number of items to return per page. From five to two hundred as maximum.
  • timestamp: (Optional) An integer as UNIX time in seconds to limit the search. The search will be filtered by values less or equal than timestamp.
Returns:
  • HistoryIPResponse(): an object containing the HTTP status code response, the error (if any) and the object containing all historical information.
Raises:
GetHistoryDomain(domain, timestamp=None, items=5, page=1)

Get the list of transactions of a given Domain in our database. For experts who wish to know the historical activity of the given domain in our database.

Arguments:
  • domain: A string containing the FQDN to obtain the historical information.
  • page: (Optional) An integer starting with 1 to paginate the results of the query.
  • items: (Optional) An integer with the number of items to return per page. From five to two hundred as maximum.
  • timestamp: (Optional) An integer as UNIX time in seconds to limit the search. The search will be filtered by values less or equal than timestamp.
Returns:
  • HistoryDomainResponse(): an object containing the HTTP status code response, the error (if any) and the object containing all historical information.
Raises:
GetHistoryEmail(email, timestamp=None, items=5, page=1)

Get the list of transactions of a given Email in our database. For experts who wish to know the historical activity of the given Email in our database.

Arguments:
  • email: A string containing the Email to obtain the historical information.
  • page: (Optional) An integer starting with 1 to paginate the results of the query.
  • items: (Optional) An integer with the number of items to return per page. From five to two hundred as maximum.
  • timestamp: (Optional) An integer as UNIX time in seconds to limit the search. The search will be filtered by values less or equal than timestamp.
Returns:
  • HistoryEmailResponse(): an object containing the HTTP status code response, the error (if any) and the object containing all historical information.
Raises:
GetQuarantineIP()

Get the list of IP addresses in the quarantine. Quarantine is a private exclusion lists based on user IP address properties.

Returns:
  • QuarantineIPResponse(): an object containing the HTTP status code response, the error (if any) and the object containing all the IP addresses in the quarantine.
GetQuarantineCountry()

Get the list of countries in the quarantine. Quarantine is a private exclusion lists based on user IP address properties. In this case, the country the IP belongs to.

Returns:
  • QuarantineCountryResponse(): an object containing the HTTP status code response, the error (if any) and the object containing all the countries in the quarantine.
GetQuarantineContinent()

Get the list of continents in the quarantine. Quarantine is a private exclusion lists based on user IP address properties. In this case, the continent the IP belongs to.

Returns:
  • QuarantineContinentResponse(): an object containing the HTTP status code response, the error (if any) and the object containing all the continents in the quarantine.
GetQuarantineAS()

Get the list of Autonomous Systems in the quarantine. Quarantine is a private exclusion lists based on user IP address properties. In this case, the AS the IP belongs to.

Returns:
  • QuarantineASResponse(): an object containing the HTTP status code response, the error (if any) and the object containing all the AS in the quarantine.
AddQuarantineIP(ip_address, ttl=3600)

Add an IP address for a given time to live in the quarantine list.

Arguments:
  • ip_address: A string containing a valid IP address to include in the QUARANTINE-IP list.
  • ttl: (Optional) An integer as in seconds to limit the time to live the IP address in the list. By default is 3600 seconds. Zero value if the IP address will never expire in the list.
Returns:
  • Response(): an object containing the HTTP status code response and the error (if any).
Raises:
AddQuarantineCountry(country, ttl=3600)

Add a country for a given time to live in the quarantine list.

Arguments:
  • country: A string containing a valid ISO-3166-1 country to include in the QUARANTINE-IP list.
  • ttl: (Optional) An integer as in seconds to limit the time to live the country in the list. By default is 3600 seconds. Zero value if the country will never expire in the list.
Returns:
  • Response(): an object containing the HTTP status code response and the error (if any).
Raises:
AddQuarantineContinent(continent, ttl=3600)

Add a continent for a given time to live in the quarantine list.

Arguments:
  • continent: A string containing a valid continent to include in the QUARANTINE-CONTINENT list. Valid codes are EU, AS, NA, AF, AN, SA, OC.
  • ttl: (Optional) An integer as in seconds to limit the time to live the continent in the list. By default is 3600 seconds. Zero value if the continent will never expire in the list.
Returns:
  • Response(): an object containing the HTTP status code response and the error (if any).
Raises:
AddQuarantineAS(asnum, ttl=3600)

Add an Autonomous System number for a given time to live in the quarantine list.

Arguments:
  • asnum: An integer containing a valid Autonomous System Number (ASN to include in the QUARANTINE-AS list.
  • ttl: (Optional) An integer as in seconds to limit the time to live the AS in the list. By default is 3600 seconds. Zero value if the AS will never expire in the list.
Returns:
  • Response(): an object containing the HTTP status code response and the error (if any).
Raises:
DeleteQuarantineIP(ip_address)

Delete an IP address from the quarantine list.

Arguments:
  • ip_address: A string containing a valid IP address to remove of the QUARANTINE-IP list.
Returns:
  • Response(): an object containing the HTTP status code response and the error (if any). If the IP address does not exists, it will also return a 200 status code.
Raises:
DeleteQuarantineCountry(country)

Delete a country from the quarantine list.

Arguments:
  • country: A string containing a valid ISO-3166-1 country code to remove of the QUARANTINE-COUNTRY list.
Returns:
  • Response(): an object containing the HTTP status code response and the error (if any). If the country does not exists, it will also return a 200 status code.
Raises:
DeleteQuarantineContinent(continent)

Delete a continent from the quarantine list.

Arguments:
  • continent: A string containing a valid continent code to remove of the QUARANTINE-CONTINENT list. Valid codes are EU, AS, NA, AF, AN, SA, OC.
Returns:
  • Response(): an object containing the HTTP status code response and the error (if any). If the continent does not exists, it will also return a 200 status code.
Raises:
DeleteQuarantineAS(asn)

Delete an Autonomous System from the quarantine list.

Arguments:
  • asn: A string containing a valid Autonomous System Number (ASN) to remove of the QUARANTINE-AS list.
Returns:
  • Response(): an object containing the HTTP status code response and the error (if any). If the ASN does not exists, it will also return a 200 status code.
Raises: