laravel-gtm/nerdydata-sdk

Laravel-ready PHP SDK for the NerdyData API, built with Saloon.

v0.1.0 2026-07-17 02:13 UTC

Requires

• php: ^8.4
• illuminate/support: ^11.0 || ^12.0 || ^13.0
• saloonphp/laravel-plugin: ^4.0
• saloonphp/rate-limit-plugin: ^2.0
• saloonphp/saloon: ^4.0

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.18
• orchestra/testbench: ^9.0 || ^10.0
• pestphp/pest: ^3.8
• phpstan/phpstan: ^2.1

MIT

Published on Packagist.org on 2026-07-17 02:14 UTC

README

A typed PHP 8.4 SDK for version 1.1.1 of the NerdyData API, built with Saloon 4 and ready for Laravel 11, 12, or 13.

It covers every operation in the OpenAPI 3.0 contract:

• code, title, and meta-description search;
• asynchronous CSV downloads;
• report suggestions;
• domain metadata and technology profiles.

Installation

composer require laravel-gtm/nerdydata-sdk

Configuration

Laravel discovers the service provider automatically. Publish its configuration:

php artisan vendor:publish --tag=nerdydata-sdk-config

Set your API key:

NERDYDATA_TOKEN=your-api-key
NERDYDATA_BASE_URL=https://api.nerdydata.com
NERDYDATA_AUTH_HEADER=api_key

NERDYDATA_BASE_URL and NERDYDATA_AUTH_HEADER are optional. Their shown values are the defaults from the API contract.

For standalone use:

use LaravelGtm\NerdyDataSdk\NerdyDataSdk;

$sdk = NerdyDataSdk::make(token: 'your-api-key');

In Laravel, resolve NerdyDataSdk from the container:

$sdk = app(\LaravelGtm\NerdyDataSdk\NerdyDataSdk::class);

Structured searches

Use SearchQuery to compose all, any, and none terms. A term may contain code or a report UUID returned by suggestions().

use LaravelGtm\NerdyDataSdk\ValueObjects\SearchQuery;
use LaravelGtm\NerdyDataSdk\ValueObjects\SearchTerm;

$search = new SearchQuery(
    all: [SearchTerm::report('d513e568-ad32-44b5-b0c8-1b7d3fbe88a6')],
    any: [SearchTerm::code('cdn.shopify.com')],
    none: [SearchTerm::code('cdn.bigcommerce.com')],
);

// Convenience forms put every supplied term in the `all` bucket.
$search = SearchQuery::code('cdn.shopify.com', 'shopify.js');
$search = SearchQuery::report('d513e568-ad32-44b5-b0c8-1b7d3fbe88a6');

Search endpoints

// GET /search
$results = $sdk->searchCode($search, start: 25);

foreach ($results->sites as $site) {
    $site->domain;
    $site->company;
    $site->linkedin;
}

$results->total;
$results->nextPage;

// GET /search/title
$titles = $sdk->searchTitles(SearchQuery::code('Shopify'));

// GET /search/description
$descriptions = $sdk->searchDescriptions(SearchQuery::code('commerce platform'));

Title and description searches return MetaSearchResults, whose sites contain the documented domain and url fields. Code searches return SearchResults with full Site records and the optional nextPage cursor.

The API still documents deprecated query, report, and page parameters. They remain available explicitly:

use LaravelGtm\NerdyDataSdk\ValueObjects\SearchInput;

$results = $sdk->searchCode(
    SearchInput::query('cdn.shopify.com'),
);

$nextPage = $sdk->searchCode(page: 'previous-next-page-value');

$titles = $sdk->searchTitles(SearchInput::report('report-uuid'));

Downloads

Create a job, then poll its hash until file is present. Download URLs are valid for 30 minutes.

// POST /downloads
$download = $sdk->createDownload(SearchQuery::code('cdn.shopify.com'));

// GET /downloads/{id}
$download = $sdk->getDownload($download->hash);

if ($download->isReady()) {
    $file = $download->file;
}

createDownload() also accepts SearchInput::query() and SearchInput::report() for the deprecated request-body forms.

Suggestions and domains

// GET /suggestions
$reports = $sdk->suggestions('shopify');
$reportId = $reports[0]->uuid;

// GET /domains/{domain}
$domain = $sdk->domain('oracle.com');

// GET /domains/{domain}/technologies
$technologies = $sdk->domainTechnologies('allbirds.com');
$profile = $technologies->first();

Non-successful HTTP responses throw Saloon request exceptions. The API's { "message": "..." } body can be mapped with Responses\ErrorResponse when needed.

Development

composer test
composer analyse
composer lint

License

MIT. See LICENSE.