README

Introduction

SimilarWeb is a project created by SimilarGroup company. It collects and provides access to various website analytics. This is a PHP library implementing easy access to their API.

If you want to know what changed in each version please refer to CHANGELOG file in the root of this repository.

Requirements:

PHP 5.3 (namespaces),
Symfony's YAML library (parsing mapping data).

Installation:

This library is available on Packagist and uses thunderer/similarweb-api alias. If you use Composer (and if you don't I don't know what you're waiting for) you can composer require it:

composer require thunderer/similarweb-api

Alternatively you can place it manually inside your composer.json:

(...)
"require": {
    "thunderer/similarweb-api": "dev-master"
}
(...)

and then run composer install or composer update as required.

This library requires Request and Response classes generated from its configuration. If you're using Composer please add proper entries to "scripts" block to composer.json file like in the example below to have them generated automatically during install or update. In any other case please manually run php bin/generate from command line. You can read more on this topic in Internals section.

Utility class ClientFacade containing easy to use interface is also generated just after Request and Response classes.

"scripts": {
    "post-install-cmd": "php vendor/thunderer/similarweb-api/bin/generate",
    "post-update-cmd": "php vendor/thunderer/similarweb-api/bin/generate"
}

You can of course make it a git submodule, download and place it in your project next to your regular code or something, but really, do yourself (and the whole industry) a favor and use Composer.

Usage:

All APIs implemented in this library have the Request and Response classes named corresponding to those defined in SimilarWeb API documentation. Expected data should be retrieved by first visiting SimilarWeb API documentation and then using Request class with the same name located in src/Request directory. Method getResponse() demonstrated below will automatically match, create and return matching Response class object which can be type hinted and relied on. There is also ClientFacade class which contains easy to use interface (note that this class is auto-generated):

use Thunder\SimilarWebApi\Client;
use Thunder\SimilarWebApi\ClientFacade;
use Thunder\SimilarWebApi\RawResponse;
use Thunder\SimilarWebApi\Request\Traffic as TrafficRequest;
use Thunder\SimilarWebApi\Response\Traffic as TrafficResponse;

// create client object
$client = new Client($yourUserKey, $desiredFormat);
$clientFacade = new ClientFacade($client);

// fetch response by passing API call name and desired domain
$response = $clientFacade->getTrafficResponse('kowalczyk.cc');
// or if you prefer to do it manually
$response = $client->getResponse(new TrafficRequest('kowalczyk.cc'));

// domain response class provides readable interface to get required information
/** @var $response TrafficResponse */
$rank = $response->getGlobalRank();

// there is also a raw response class which is used underneath
/** @var $rawResponse RawResponse */
$rawResponse = $response->getRawResponse();
$globalRank = $rawResponse->getValue('globalRank');

// check it by comparing both values:
assert($rank === $globalRank, 'Report an issue if you see this text.');

Internals

The core of this library is a file called mapping.yaml which contains definition of data returned by each API. This library requires existence of Request and Response classes generated using bin/generate script from data stored in that file. In this section API GlobalRank will be described and referred to as an example. This is its mapping configuration:

GlobalRank:
  path: globalRank
  url: /Site/{domain}/{path}?Format={format}&UserKey={token}
  values:
    rank:
      json: { field: Rank }
      xml: { field: Rank }

It states that there is an API named GlobalRank which uses URL part globalRank and returns one value which library will refer to as rank, reading it either from JSON key Rank or XML element Rank. From such configuration bin/generate script will create two classes: Thunder\SimilarWebApi\Request\GlobalRank and Thunder\SimilarWebApi\Response\GlobalRank which are used respectively as input and output objects passed to and returned from Thunder\SimilarWebApi\Client::getResponse() method.

APIs return associative arrays with keys containing four types of data:

value: primitive value such as integer, string or date (rank: 2),
array: array of primitive values of one type (months: [1, 3, 5]),
map: key-value associative arrays (domains: [google.com: 3, google.pl: 7]),
tuple: associative array with selected pieces of data as keys and associative values of the rest as values.

During either composer install, composer update or manual execution of php bin/generate command, API mapping configuration is used to generate domain request and response classes with methods hiding library complexity behind readable accessors. Such approach makes it possible to have readable class API, good IDE autocompletion and highlighting possibilities with no additional programming work. When response is parsed all elements of given type are put inside their containers and those response classes act as a facade for raw response object.

$response = $client->getResponse(/* ... */);
$rawResponse = $response->getRawResponse();

$response->getRank() === $rawResponse->getValue('rank');

License

See LICENSE file in the root of this repository.

thunderer / similarweb-api

Maintainers

Details