General API Documentation

Standardised responses across all APIs

Get your FREE API key

Authentication

Authentication is simple, append the private key that can be found in your dashboard to the API end point like in the example to the right. That's it, your request is now authenticated and logged in your api call log.

https://api.webcargo.io/whois?key=YOUR_KEY_HERE
https://api.webcargo.io/whois?key=YOUR_KEY_HERE
https://api.webcargo.io/whois?key=YOUR_KEY_HERE

Response codes

The WebCargo API uses standard HTTP response codes to communicate the result of an API call. Below is a list of the possible codes that could be returned and how they should be interpreted.

PARAMETER

DESCRIPTION

200

Processed

The command was processed successfully.

422

Unprocessable

Well formatted request however some technical issue is preventing the serving of the request, e.g. an unresponsive WHOIS server.

400

Command unknown

The end-point you have sent the request to is not valid. For example you may have sent the request to /idontexist rather than /whois.

405

Command invalid

The HTTP request method used is not compatible with the selected end-point. This can occur when using POST rather than GET, for example.

409

Command malformed

The request has been incorrectly constructed. This can occur when omitting required parameters or providing them in the wrong type.

401

Unauthorized

The request was not authorised. This can occur when using an incorrect key, if the server IP is not on the accounts white list, if the account is banned, or the account email address has not been verified.

402

Billing issue

The request was refused due to a billing issue with the associated account. Please check you have sufficient funding associated with your account and no outstanding invoices.

500

Internal Server Error

The client did everything correctly, but we've had an internal issue.

Whois API

Retrieve formatted Whois data in Json format our REST API

Get your FREE API key

Whois API Parameters

This end-point accepts a domain name as the argument and performs a Whois lookup. The result of that look up is then parsed into a Json object and returned to your client.

PARAMETER

DESCRIPTION

identifier

The domain name or IP address to lookup.

// api call
curl 'https://api.webcargo.io/whois?key=YOUR_KEY_HERE&identifier=google.com'

// api response
{
 "result":{
    "name":"google.com",
    "created":"1997-09-15 07:00:00",
    "changed":"2015-06-12 17:38:52",
    "expires":"2020-09-14 00:00:00",
    "dnssec":"unsigned",
    "registered":true,
    "status":[
       "clientUpdateProhibited (https:\/\/www.icann.org\/epp#clientUpdateProhibited)",
       "clientTransferProhibited (https:\/\/www.icann.org\/epp#clientTransferProhibited)",
       "clientDeleteProhibited (https:\/\/www.icann.org\/epp#clientDeleteProhibited)",
       "serverUpdateProhibited (https:\/\/www.icann.org\/epp#serverUpdateProhibited)",
       "serverTransferProhibited (https:\/\/www.icann.org\/epp#serverTransferProhibited)",
       "serverDeleteProhibited (https:\/\/www.icann.org\/epp#serverDeleteProhibited)"
    ],
    "nameservers":[
       "ns3.google.com",
       "ns4.google.com",
       "ns2.google.com",
       "ns1.google.com"
    ],
    "contacts":{
       "owner":[
          {
             "handle":null,
             "type":null,
             "name":"Dns Admin",
             "organization":"Google Inc.",
             "email":"dns-admin@google.com",
             "address":"Please contact contact-admin@google.com, 1600 Amphitheatre Parkway",
             "zipcode":"94043",
             "city":"Mountain View",
             "state":"CA",
             "country":"US",
             "phone":"+1.6502530000",
             "fax":"+1.6506188571",
             "created":null,
             "changed":null
          }
       ],
       "admin":[
          {
             "handle":null,
             "type":null,
             "name":"DNS Admin",
             "organization":"Google Inc.",
             "email":"dns-admin@google.com",
             "address":"1600 Amphitheatre Parkway",
             "zipcode":"94043",
             "city":"Mountain View",
             "state":"CA",
             "country":"US",
             "phone":"+1.6506234000",
             "fax":"+1.6506188571",
             "created":null,
             "changed":null
          }
       ],
       "tech":[
          {
             "handle":null,
             "type":null,
             "name":"DNS Admin",
             "organization":"Google Inc.",
             "email":"dns-admin@google.com",
             "address":"2400 E. Bayshore Pkwy",
             "zipcode":"94043",
             "city":"Mountain View",
             "state":"CA",
             "country":"US",
             "phone":"+1.6503300100",
             "fax":"+1.6506181499",
             "created":null,
             "changed":null
          }
       ]
    },
    "registrar":{
       "id":"292",
       "name":"MarkMonitor, Inc.",
       "email":"abusecomplaints@markmonitor.com",
       "url":"http:\/\/www.markmonitor.com",
       "phone":"+1.2083895740"
    }
 }
}
//coming soon

Screenshot API

Flexible webpage screenshot REST API

Get your FREE API key

Screenshot API Parameters

This end-point accepts a URL as the argument and creates a screenshot of the website located at that address. The result of this operation is returned as a base64 encoded image wrapped in a Json object.

PARAMETER

DESCRIPTION

url

The web address of the page to render and capture.

file_type

Optional

The desired file type of the screenshot. Choose between 'png' and 'jpeg'.

width

Optional

The width of the client used to render the webpage, specified in pixels. The default value if omitted is 1920.

height

Optional

The height of the client used to render the webpage, specified in pixels. The default value if omitted is 1080.

quality

Optional

A number between 1 and 100 (inclusive) that dictates the quality of the screen grab with 100 being best quality. This setting is only available on jpeg exports. The default value if omitted is 85. PNG Images will always be rendered at the highest quality.

transparent

Optional

If enabled a default white background will not be inserted by the rendering engine. Any content on the page without a background colour will be rendered transparent using the alpha channel. Set to "true" or 1 to enable, set to "false" or 0 to disable. This setting is only available on PNG images. The default value if omitted is "false".

full_page

Optional

When this parameter is set to "false" or 0 only the above the fold content will be captured. Where above the fold is defined by the box specified by the width & height parameters. Set to "true" or 1 to capture the entire page. This setting is only available with PNG and jpeg export types. The default value if omitted is "false".

request_timeout

Optional

The amount of time expressed in seconds to wait before the screenshot is taken after the page and all elements have been loaded. The default value if omitted is 1 second.

return_type

Optional

Specifies the method used to serve the screenshot, currently the following types (i.e. acceptable values to pass) are supported:

  • 1 = return a base64 encoded version of the image (default)
  • 2 = return a HTTP link to the image hosted on our file server, available for 5 minutes

//api call
curl 'https://api.webcargo.io/screenshot?key=YOUR_KEY_HERE&url=example.com&width=1200&height=800'

//api response
{
 "base64": "iVBORw0KGgoAAAANSUhEUgAABLAAAAMgCAYAAAAz4JsCAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEwAACxMBAJqcGAAAIABJREFUeJzs3Xl4FFXa9/FfJ4QkhCxCgIAigUDYZVM2BUUIguOoIKKyM0IEZGdYnBEYotFHBYQBUUFAGYwCj4OIgAqKKEscmQFGEBBCAAEF2RKUkJDl/cMn/abp6qS60yFF+vu5Li7N6VOn7rNUpftOVbXt4sX0PAEAAAAAAAAW5VfaAQAAAAAAAACFIYEFAA ... ACANAELAAAAgDQBCwAAAIA0AQsAAACANAELAAAAgDQBCwAAAIC0/wBqRycyXwTWgAAAAABJRU5ErkJggg==",
 "prefix": "data:image\/png;base64,"
}
// coming soon


// coming soon

            

Geolocate IP address API

Easily check the location of any IP address with our REST API

Get your FREE API key

Geolocate IP API Parameters

This end-point accepts an IP address and returns geolocation and contextual data about its location.

PARAMETER

DESCRIPTION

ip_address

The IP address to geo-locate.

//api call
curl 'https://api.webcargo.io/ip?key=YOUR_KEY_HERE&ip_address=78.157.211.235'

//api response
{  
   "country_code":"GB",
   "country_name":"United Kingdom",
   "city":"Hornchurch",
   "postal_code":"RM11",
   "location_long":0.2167,
   "location_latitude":51.55,
   "location_accuracy_radius":20,
   "name":{  
      "common":"United Kingdom",
      "name_official":"United Kingdom of Great Britain and Northern Ireland"
   },
   "cctld":[  
      ".uk"
   ],
   "currency_codes":[  
      "GBP"
   ],
   "calling_codes":[  
      "44"
   ],
   "capital_city":"London",
   "region":"Europe",
   "subregion":"Northern Europe",
   "languages":{  
      "eng":"English"
   },
   "latlng":[  
      54,
      -2
   ],
   "demonym":"British",
   "landlocked":false,
   "borders":[  
      "IRL"
   ],
   "area":242900
}
//coming soon
//coming soon

Domain Check API

Deeply probe a domains availably with our REST API

Get your FREE API key

Domain Check API Parameters

This end-point accepts a domain as the argument and performs an availability check, returning the status of the domain as a boolean embedded in a Json object.

PARAMETER

DESCRIPTION

domain

The domain name for which to check availability.

//api call
curl 'https://api.webcargo.io/availability?key=YOUR_KEY_HERE&domain=google.com'

//api response
{
 "is_available":false
}

// coming soon

        


// coming soon

        

Email Validation API

Deeply probe any email address with our REST API

Get your FREE API key

Email API Parameters

This end-point accepts a supposed email address as the argument and performs multiple in-depth validation checks and returns results in a Json object.

PARAMETER

DESCRIPTION

email

The supposed email address to investigate.

curl 'https://api.webcargo.io/email?key=YOUR_KEY_HERE&email=support@webcargo.io'
// coming soon


      
// coming soon

Response

The following table explains the possible response fields from this end-point.

PARAMETER

DESCRIPTION

valid_form

Set to true if the submitted email address passes a cursory check of valid form. Do not use the output of this field alone to determine deliverability - please see the 'deliverable' field described below.

role

Set to true if the email address pertains to a role in an organisation such as 'support' or 'billing' rather than a specific individual.

disposable

Set to true if the email address is hosted and managed by a disposable ESP.

free

Set to true if the email address is hosted at an ESP which is free to use by the general public (excluding disposable hosts), examples include Gmail and Hotmail.

typo

Set to true if a possible typographical error was detected in the email address.

suggestion

Set to null if no typographical error was detected or set to a single string value containing an alternate address suggestion if an error was detected.

valid_mx

Set to true if the host of the email address is associated with a valid mail exchange server.

deliverable

This field is a composite of various fields above, it will be set to true if the supplied email address meets the minimum requirements to be a deliverable valuable email, in short this field is set to true if the address has valid form and MX records, has no typos, and is disposable.

{
   "valid_form":true,
   "role":false,
   "disposable":false,
   "free":false,
   "typo":false,
   "suggestion":null,
   "valid_mx":true,
   "deliverable":true
}
{
   "valid_form":true,
   "role":false,
   "disposable":false,
   "free":false,
   "typo":false,
   "suggestion":null,
   "valid_mx":true,
   "deliverable":true
}
{
   "valid_form":true,
   "role":false,
   "disposable":false,
   "free":false,
   "typo":false,
   "suggestion":null,
   "valid_mx":true,
   "deliverable":true
}