Base Usage - jovixv/dataforseo_client GitHub Wiki

In this Wiki we refer to the concept of the model, which constitutes a class that implements the functionality of an API request. Examples were drawn from the RelatedKeywords model of the KeywordFinder API.

Step 1.

First things first, we have to copy the main DFSClient class along with the necessary models and add them to the namespace.

use DFSClient\DFSClient;
use DFSClient\Models\KeywordsFinderApi\Related_Keywords\RelatedKeywords;

Step 2. You'll need to initialize objects.

You must specify your DataForSEO credentials in the DFSClient constructor. Login and password are compulsory to access the APIs involved.

 $DFSClient = new DFSClient('SET Your Login', 'SET Your Password'); // Client's initialization
 $model     = new RelatedKeywords(); //initialization of the needed model. 

If you're using CMS or framework, or just a file structure, you don't need to initialize this object everytime. It would be enough to do it once, before calling the DFS Client models. DFSClient is implemented as a singelton.

 $DFSClient = new DFSClient('SET Your Login', 'SET Your Password'); // Initialization of the client.

Step 3.
After model's initialization, you can use it as a builder -- all available parameters are available in the documentation. Builder

Method ->setOpt('field','param') sets the parameters required by DFSapi to make a request; in other words it sets a payload. The first argument is the parameter's name, the second is its values. Values can be int, string, array. Names of parameters which are necessary for the chosen API-endpoint can be found at https://docs.dataforseo.com.

Method -get() handles request to the api, processes data and provides you with ResponseCollection. Please, notice that get is not "the http request method." It's the internal method used for data retrieval.

$completed  = $model->setOpt('keyword','big data')
    ->setOpt('language', 'en')
    ->setOpt('country_code', 'US')
    ->setOpt('depth', 2)
    ->get();

Step 3

The third step is to verify the request's success.

if (!$completed->isSuccessFul())
    dd($completed);

Step 4

Upon the successful completion of the request, you can process the obtained data. From the code described above, you have the $completed variable, which stores the ResponseCollection object.

ATTENTION

ResponseCollection is a simple object implementing the Traversable - ItteratorAgregate. Everything is configured in such a way that if you iterate the $completed variable as described below, you will get main data from the response of DataForSEO API. At first glance, it may seem a little sophisticated. However, it's easy to understand if you imagine that while passing the cycle under this variable, it's becoming an array containing the main result. When the given variable isn't being iterated, you can treat it like an object - in so doing, the object is a subset of the JSON response. Basically, it says any DataForSEO API returns the status with its responses. Here's how you can get the status:

$completed->status  // will get the status from the JSON response of DataForSEO.
$completed->results_time // will get the execution time from the JSON response of DataForSEO.

As mentioned above, we took the RelatedKeywords API-endpoint as an example. The response of this API has the following pattern:

{
    "status": "ok",
    "results_time": "0.5441 sec.",
    "results_count": 1,
    "results": {
        "11913049": {
            "post_id": "11913049",
            "task_id": 12937,
            "meta": {
                "keyword": "mountain house",
                "depth": 2,
                "limit": 1,
                "offset": 0,
                "orderby": "cpc,desc",
                "total_count": 71,
                "result_count": 1
            },
            "related": [
                {
                    "key": "freeze dried food reviews",
                    "country_code": "US",
                    "language": "en",
                    "search_volume": 50,
                    "competition": 1,
                    "cpc": 6.746295,
                    "history": [
                       ...
                    ]
                }
            ]
        }
    }
}

When iterating $completed in the foreach cycle, it seems that it refers to

            "related": [
                {
                    "key": "freeze dried food reviews",
                    "country_code": "US",
                    "language": "en",
                    "search_volume": 50,
                    "competition": 1,
                    "cpc": 6.746295,
                    "history": [
                       ...
                    ]
                }
            ]

Here's how iteration looks like

foreach ($completed as $key=>$item) {
    dump($item);
}

Here's how all the code looks like:

require_once '../../../../vendor/autoload.php';

use DFSClient\DFSClient;
use DFSClient\Models\KeywordsFinderApi\Related_Keywords\RelatedKeywords;

$DFSClient = new DFSClient('SET your password','SET your password');
$model     = new RelatedKeywords();

$completed  = $model->setOpt('keyword','big data')
    ->setOpt('language', 'en')
    ->setOpt('country_code', 'US')
    ->setOpt('depth', 2)
    ->get();


if (!$completed->isSuccessFul())
    dd($completed);

dd($completed);
// you can call property as described below
echo 'status: '       .$completed->status        ."<br>";
echo 'results_time: ' .$completed->results_time  ."<br>";
echo 'results_count: '.$completed->results_count ."<br>";

foreach ($completed as $key=>$item) {
    dump($item);
}