Abstract API Python SDK

This is a simple and intuitive Python SDK for using AbstractAPI's services.

Current supported services:

All AbstractAPI services are supported by this SDK (16th. January 2023).

• Email Validation
• Phone Validation
• VAT Validation/Calculation/Categories
• IBAN Validation
• IP Geolocation
• Holidays Lookup
• Exchange Rates Live/Convert/Historical
• Company Enrichment
• Timezone Current/Conversion
• Avatars Generation
• Website Screenshot
• Website Scrape
• Image Processing

Installation:

Install using pip:

pip install abstract-api

Getting Started:

To use any service, you must have your API key for that service.
To do that, you have two options:

1. Export your API key as an environment variable:
   To export an API key for a service, you should follow this scheme:

   ABSTRACTAPI_{SERVICE_NAME}_API_KEY
   

   Note: SERVICE_NAME is all uppercase and underscore separated.
   For example, to export your Email Validation service API key, use the following environment variable name:

   ABSTRACTAPI_EMAIL_VALIDATION_API_KEY
   

   Example in terminal:

   export ABSTRACTAPI_AVATARS_API_KEY=612345e4a63044b47a1234567a53cc81

   In initialization, you don't have to pass an API key:

   fromabstract_apiimportEmailValidationservice=EmailValidation()

2. Pass your API key during service class instantiation:
   Example:

   fromabstract_apiimportEmailValidationservice=EmailValidation(api_key="612345e4a63044b47a1234567a53cc81")

Note: If both options were used simultaneously, the API key that was passed to constructor is used.

Examples:

Notes:

• Each service response is represented as a response class to provide an intuitive
  Pythonic way for handling responses.
• All public interfaces of all services classes are modeled after AbstractAPI endpoints interfaces and responses.
  Example: Email Validation service endpoint expects the following parameters:
  • api_key
  • email
  • auto_correct
    The EmailValidation class's check() method expects the same parameters email and auto_correct.
    (No need to pass api_key. It is already passed during service instantiation.)

Recommended:

• Check service class and service class response documentations.

• Response fields used in examples are not only the ones. Check documentation to see
  all the capabilities.

• Email Validation

  fromabstract_apiimportEmailValidationservice=EmailValidation(api_key="612345e4a63044b47a1234567a53cc81")
  response=service.check("example@example.com")
  ifresponse.is_valid_format:
  print("Email is valid!")
  ifresponse.is_disposable_email:
  print("Email is disposable, not this time :( ")

  EmailValidation documentation can be found here
  EmailValidationResponse documentation can be found here

• Phone Validation

  fromabstract_apiimportPhoneValidationservice=PhoneValidation(api_key="612345e4a63044b47a1234567a53cc81")
  response=service.check("20123456789")
  ifresponse.valid:
  print("Phone number is valid!")

  PhoneValidation documentation can be found here
  PhoneValidationResponse documentation can be found here

• VAT Validation/Calculation/Inquiry

  fromabstract_apiimportVATservice=VAT(api_key="612345e4a63044b47a1234567a53cc81")
  validation_response=service.check("SE556656688001")
  calculation_response=service.calculate(amount=100, country_code="EG")
  categories_response=service.categories("EG")

  VAT documentation can be found here
  VATValidationResponse documentation can be found here
  VATCalculationResponse documentation can be found here
  VATCategoriesResponse documentation can be found here

• IBAN Validation

  fromabstract_apiimportIBANValidationservice=IBANValidation(api_key="612345e4a63044b47a1234567a53cc81")
  response=service.check("BE71096123456769")
  ifresponse.is_valid:
  print("IBAN is valid!")

  IBANValidation documentation can be found here
  IBANValidationResponse documentation can be found here

• IP Geolocation

  fromabstract_apiimportIPGeolocationservice=IPGeolocation(api_key="612345e4a63044b47a1234567a53cc81")
  response=service.check("156.215.70.7", fields=["city"])
  print("IP is in: ", response.city)

  IPGeolocation documentation can be found here
  IPGeolocationResponse documentation can be found here

• Holidays Lookup

  fromabstract_apiimportHolidaysservice=Holidays(api_key="612345e4a63044b47a1234567a53cc81")
  response=service.check("EG")
  print(response.holidays)

  Holidays documentation can be found here
  HolidaysResponse documentation can be found here

• Exchange Rates Live/Convert/Historical

  fromabstract_apiimportExchangeRatesservice=ExchangeRates(api_key="612345e4a63044b47a1234567a53cc81")
  live_response=service.live("USD", "EGP")
  conversion_response=service.convert("USD", "EGP", "2023-01-17", 150)
  historical_response=service.historical("USD", "2023-01-17", 150)

  ExchangeRates documentation can be found here
  LiveExchangeRatesResponse documentation can be found here
  HistoricalExchangeRatesResponse documentation can be found here
  ExchangeRatesConversionResponse documentation can be found here

• Company Enrichment

  fromabstract_apiimportCompanyEnrichmentservice=CompanyEnrichment(api_key="612345e4a63044b47a1234567a53cc81")
  response=service.check("EG")
  print(response.holidays)

  CompanyEnrichment documentation can be found here
  CompanyEnrichmentResponse documentation can be found here

• Timezone Current/Conversion

  fromabstract_apiimportTimezoneservice=Timezone(api_key="612345e4a63044b47a1234567a53cc81")
  current_response=service.current("Cairo, Egypt", "82.111.111.111")
  conversion_response=service.convert((30.0594627, 31.1758899), "Cairo, Egypt")

  Timezone documentation can be found here
  CurrentTimezoneResponse documentation can be found here
  TimezoneConversionResponse documentation can be found here

• Avatars Generation

  fromabstract_apiimportAvatarsservice=Avatars(api_key="612345e4a63044b47a1234567a53cc81")
  response=service.create("John Doe", 200)
  file=open("logo.png", "wb+")
  file.write(response.content)

  Avatars documentation can be found here
  AvatarsResponse documentation can be found here

• Website Screenshot

  fromabstract_apiimportWebsiteScreenshotservice=WebsiteScreenshot(api_key="612345e4a63044b47a1234567a53cc81")
  response=service.capture("https://www.github.com", capture_full_page=False)
  file=open("github-home-screenshot.png", "wb+")
  file.write(response.content)

  WebsiteScreenshot documentation can be found here
  WebsiteScreenshotResponse documentation can be found here

• Website Scrape

  fromabstract_apiimportWebScrapingservice=WebScraping(api_key="612345e4a63044b47a1234567a53cc81")
  response=service.scrape("https://www.github.com", proxy_country="EG")
  file=open("github-home-screenshot.png", "wb+")
  file.write(response.content)

  WebScraping documentation can be found here
  WebScrapingResponse documentation can be found here

• Image Processing

  fromabstract_apiimportImageProcessingfromabstract_api.image_processing.strategiesimportCrop, Exactresize=Exact(height=200, width=200)
  service=ImageProcessing(api_key="612345e4a63044b47a1234567a53cc81")
  image=open('example.png', 'rb')
  response=service.upload(image, lossy=False, resize=resize)
  print(response.url)
  response=service.url("https://example.com/image.jpeg", lossy=False, resize=resize)
  print(response.url)

  ImageProcessing documentation can be found here
  ImageProcessingResponse documentation can be found here

Handling Errors

1. If something wrong happened on client side:

fromabstract_apiimportImageProcessingfromabstract_api.core.exceptionsimportClientRequestErrorservice=ImageProcessing(api_key="612345e4a63044b47a1234567a53cc81")
try:
service.url("https://example.com/image.jpeg", quality=150)
exceptClientRequestErrorase:
print("Some error happended from client's side")
print(str(e))
# 'quality must be in range from 1 to 100 (inclusive)'

2. If the service endpoint returns a status code that is not 200 or 204.
   (200 and 204 are -currently- the only accepted status codes.)

fromabstract_apiimportImageProcessingfromabstract_api.core.exceptionsimportAPIRequestErrorservice=ImageProcessing(api_key="612345e4a63044b47a1234567a53cc81")
try:
service.url("https://example.com/image.jpeg", quality=150)
exceptAPIRequestErrorase:
ife.status_code==500:
print("AbstractAPI service is currently having a problem")
print(str(e))