API_Documentation
Help_Topics

How to use the Webmetrics APIs

The Webmetrics APIs are provided as RESTful web services. To perform an action using the Webmetrics API, you need to send a GET or POST request to the API URL specifying a method, a valid signature and some arguments, and you will receive a formatted response.

The Webmetrics API URL is: https://api.webmetrics.com/v2/ The trailing slash is important and all parameters must follow that.

For each API, you must specify a "method" parameter with the name of the method you wish to call. For example, if you wish to use the "maintenance.getServiceStatus" API, you would specify "method=maintenance.getServiceStatus" as one of the parameters sent to the API URL. The full path would resemble:

https://api.webmetrics.com/v2/?method=maintenance.getServiceStatus&username=demo&serviceid=4234234&sig=3f333e940cab610ef9c2e5d9872e77cb42a2fd87

API calls that pertain to a specific service require that you send the service ID as a request parameter. Some APIs allow requests for multiple services. In such case you need to send the serviceid parameter for each service that you need. In order to get the service IDs for your services, use the maintenance.getServices API.

How to compose a valid signature

The signature parameter (sig) is composed of a SHA1 hash of your username, your API key (found in the Webmetrics' web console, under 'My Account'), and the current epoch time appended together in that order. The SHA1 hash needs to be submitted as a base64 encoded string. Returned string will only contain characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+', '=' and '/'. You must url encode the signature when making a GET request.
You can get the current epoch time in several languages as follows:

Java long epoch = System.currentTimeMillis()/1000;
Perl time
PHP time()
Ruby Time.now (or Time.new).
Python import time first, then TIMESTAMP = str(time.time()).partition(".")[0]
C# int epoch = (int)(DateTime.UtcNow - new DateTime(1970, 1, 1)).TotalSeconds;
JavaScript Math.round(new Date().getTime()/1000.0) getTime() returns time in milliseconds.

The timestamp will be accepted for a period of 5 min.

Examples of composing a valid signature

These signatures must be url encoded before you use them

PHP:

<?php
$method    = "maintenance.getServices";
$api_key   = "074e0c4b016258407bd9830112fd850973a96543";
$username  = "demoaccount";
$timestamp = time();
$signature = base64_encode(sha1($username.$api_key.$timestamp, TRUE));
$signature = urlencode($signature);

$request = "https://api.webmetrics.com/v2/?method=$method&username=$username&sig=$signature";
echo file_get_contents($request);
?>

Perl:

#!/usr/bin/perl

use Digest::SHA1 qw(sha1_base64);
use URI::Escape;
use LWP::Simple;

my $method    = "maintenance.getServices";
my $api_key   = "074e0c4b016258407bd9830112fd850973a96543";
my $username  = "demoaccount";
my $timestamp = time;
my $signature = sha1_base64($username.$api_key.$timestamp);
$signature    = uri_escape($signature);

$request = "https://api.webmetrics.com/v2/?method=$method&username=$username&sig=$signature";
print get($request);

C#:

using System;
using System.Net;
using System.IO;
using System.Text;
using System.Web;

...
string method    = "maintenance.getServices";
string api_key   = "074e0c4b016258407bd9830112fd850973a96543";
string username  = "demoaccount";
int epoch        = (int)(DateTime.UtcNow - new DateTime(1970, 1, 1)).TotalSeconds;
string timestamp = epoch.ToString();
string signature = Convert.ToBase64String(new System.Security.Cryptography.SHA1CryptoServiceProvider().ComputeHash(Encoding.ASCII.GetBytes(username+api_key+timestamp)));
signature        = HttpUtility.UrlEncode(signature);

string request   = "https://api.webmetrics.com/v2/?method=" + method + "&username=" + username + "&sig=" + signature;
HttpWebRequest reqObj  = (HttpWebRequest)WebRequest.Create(request);
HttpWebResponse resObj = (HttpWebResponse)reqObj.GetResponse();
StreamReader reader    = new StreamReader(resObj.GetResponseStream());
string data            = reader.ReadToEnd();
Console.WriteLine(data);

Ruby:

#!/usr/bin/ruby

#################################
# Import all required libraries
require('rubygems')
require('digest/sha1')
require('base64')
require('cgi')
require('net/http')
require('net/https')
require('uri')
#################################

method    = "maintenance.getServices"
api_key   = "074e0c4b016258407bd9830112fd850973a96543"
username  = "demoaccount"
timestamp = Time.new().to_i
sha1      = Digest::SHA1.digest("#{username}#{api_key}#{timestamp}")
b64       = Base64.encode64(sha1.to_s.strip()).gsub("\n",'')
signature = CGI.escape(b64)

request   = "https://api.webmetrics.com/v2/?method=#{method}&username=#{username}&sig=#{signature}"
url       = URI.parse(request)
path      = "/v2/?method=#{method}&username=#{username}&sig=#{signature}"
http      = Net::HTTP.new(url.host, url.port)
http.use_ssl = (url.scheme == 'https')
reqObj    = Net::HTTP::Get.new(path)
resObj    = http.request(reqObj)
puts resObj.body

Output formats

  • There are two output formats to the APIs, XML and json. To specify and output format, simply add format=xml or format=json to your query. If no format is specified, it will default to xml.
  • JSON, or JavaScript Object Notation, is a simple machine-readable data-interchange format, which makes constructing API applications in JavaScript easy (though it can be used from other languages too!). For more information about JSON, visit json.org.