PHP

The official PHP SDK for Piloterr, with one typed method per endpoint and a generic request() for anything else.

RequirementsCopy Anchor Link

• PHP 8.1+

InstallCopy Anchor Link

composer require piloterr/sdk

Get your API keyCopy Anchor Link

Copy your API key from the Piloterr dashboard and set it in the PILOTERR_API_KEY environment variable, which the SDK reads by default. Keep it out of source control.

Quick startCopy Anchor Link

<?php

require 'vendor/autoload.php';

use Piloterr\Client;

$client = new Client(getenv('PILOTERR_API_KEY') ?: null);
$response = $client->amazonProduct(['query' => 'B09DFCB66S']);
print_r($response->data);

Async jobsCopy Anchor Link

Any call accepts is_async, which is useful past the 60-second server limit. The response is then a job_id, and the SDK can wait for the job to finish.

$submitted = $client->amazonProduct(['query' => 'B09DFCB66S', 'is_async' => true]);
$job = $client->waitForJob($submitted->data['job_id'], onProgress: static function (array $job): void {
    echo $job['status'], ' ', $job['progress'] ?? 0, "%\n";
});
print_r($job->data);

ErrorsCopy Anchor Link

A non-2xx response raises an API error with its status and message. See Status codes for the full list.

use Piloterr\Exception\ApiException;

try {
    $client->amazonProduct(['query' => 'B09DFCB66S']);
} catch (ApiException $exception) {
    echo $exception->status, ': ', $exception->getMessage();
}

RetriesCopy Anchor Link

Requests are retried up to 3 times after a network error, a 408, 500, 502, 503 or 504, or a plan rate limit. Per-key quota errors and client-side timeouts are not retried. The delay starts at 1 second and grows 1.5× per retry, and a Retry-After header wins.

$client = new Client(null, ['max_retries' => 5, 'retry_delay' => 0.5]);
$client->amazonProduct(['query' => 'B09DFCB66S'], new RequestOptions(maxRetries: 0)); // one request without retries

Batch requestsCopy Anchor Link

Run many calls at once, 10 at a time by default. One failure does not stop the others.

$inputs = ['B09DFCB66S', 'B0BSHF7WHW', 'B08N5WRWNW'];
$calls = array_map(static fn(string $value): array => ['amazonProduct', ['query' => $value]], $inputs);

foreach ($client->batch($calls, concurrency: 5) as $result) {
    if ($result->ok()) {
        print_r($result->value->data);
    } else {
        echo $inputs[$result->index], ': ', $result->error->getMessage(), "\n";
    }
}

Any endpointCopy Anchor Link

request() reaches any path, including endpoints released after your SDK version.

$response = $client->request('GET', '/v1/usage');

Common mistakesCopy Anchor Link

• Putting the API key in front-end code. Anyone could read it. Call the API from your server.
• Treating every 401 as a bad key. A 401 can also be a rate limit: read the message. The SDK retries plan rate limits for you.
• Retrying a 402. It means there are no credits or quota left, so a retry cannot succeed. See Credits.
• Waiting on long requests. Past 60 seconds, use async mode as shown above rather than raising your timeout. See Timeout.

LinksCopy Anchor Link

• Package: piloterr/sdk
• Source code: github.com/piloterr/piloterr-php
• API reference