Smarty PHP SDK

The Smarty PHP SDK enables developers to integrate address intelligence capabilities into PHP applications with minimal boilerplate code. The SDK provides unified access to APIs for address verification, geocoding, autocomplete, and data enrichment.

Contents

1. Installation
2. Authentication
3. Create an API client
4. Create and send lookups
5. Examine results
6. More examples

Installation

Install the SDK via Composer:

composer require smartystreets/phpsdk

Import the SDK into your application:

require 'vendor/autoload.php';

Authentication

Smarty offers two kinds of credentials depending on the deployment context:

• Server-side (backend, CLI, batch jobs): Auth ID + Auth Token (Secret Key pair) using StaticCredentials
• Client-side (browser, front-end, public UI): Embedded Key using SharedCredentials (restricted by domain referrer)

Access all keys through your Smarty account under Account → API Keys.

Store credentials as environment variables for security:

export SMARTY_AUTH_ID="your-auth-id"
export SMARTY_AUTH_TOKEN="your-auth-token"
export SMARTY_EMBEDDED_KEY="your-embedded-key"

For details on authentication and embedded vs. secret keys, see our authentication documentation.

Create an API client

The SDK uses a ClientBuilder to configure and create API-specific clients.

Server-side client

Example for US Street API using StaticCredentials:

use SmartyStreets\PhpSdk\StaticCredentials;
use SmartyStreets\PhpSdk\ClientBuilder;

$credentials = new StaticCredentials(
	getenv('SMARTY_AUTH_ID'),
	getenv('SMARTY_AUTH_TOKEN')
);

$client = (new
ClientBuilder($credentials))->buildUsStreetApiClient();

Browser/Frontend client

Example for US Autocomplete Pro API using SharedCredentials:

use SmartyStreets\PhpSdk\SharedCredentials;
use SmartyStreets\PhpSdk\ClientBuilder;

$credentials = new SharedCredentials(
	getenv('SMARTY_EMBEDDED_KEY'),
	'www.example.com' // your referring hostname
);

$client = (new
ClientBuilder($credentials))->buildUSAutocompleteProApiClient();

Available API clients

API	Builder method
US Street	buildUsStreetApiClient()
US ZIP Code	buildUsZIPCodeApiClient()
US Autocomplete Pro	buildUSAutocompleteProApiClient()
US Extract	buildUSExtractApiClient()
US Enrichment	buildUsEnrichmentApiClient()
US Reverse Geocoding	buildUsReverseGeoApiClient()
International Street	buildInternationalStreetApiClient()
International Autocomplete	buildInternationalAutocompleteApiClient()
International Postal Code	buildInternationalPostalCodeApiClient()

Client configuration options

$client = (new ClientBuilder($credentials))
	->retryAtMost(10)
	->withMaxTimeout(30000)
	->withUrl("https://your-self-hosted-url.example.com")
	->viaProxy("proxy.example.com", "username", "password")
	->withCustomHeader("X-Custom-Header", "value")
	->buildUsStreetApiClient();

Create and send lookups

Create lookups for addresses requiring validation. Each API has its own Lookup class that holds both input parameters and results.

Single lookup

Example for US Street API:

use SmartyStreets\PhpSdk\US_Street\Lookup;

$lookup = new Lookup();
$lookup->setStreet("1600 Amphitheatre Parkway");
$lookup->setCity("Mountain View");
$lookup->setState("CA");
$lookup->setMaxCandidates(3);
$lookup->setMatchStrategy("enhanced");

$client->sendLookup($lookup);

Batch lookup

Send up to 100 lookups in a single request using Batch:

use SmartyStreets\PhpSdk\Batch;
use SmartyStreets\PhpSdk\US_Street\Lookup;

$batch = new Batch();

$lookup1 = new Lookup();
$lookup1->setStreet("330 N 100 W");
$lookup1->setCity("Provo");
$lookup1->setState("Utah");
$lookup1->setZipcode("84601");

$lookup2 = new Lookup();
$lookup2->setStreet("1600 Amphitheatre Parkway Mountain View, CA 94043");

$batch->add($lookup1);
$batch->add($lookup2);

$client->sendBatch($batch);

Autocomplete lookup

Autocomplete lookups accept a search string directly:

use SmartyStreets\PhpSdk\US_Autocomplete_Pro\Lookup;

$lookup = new Lookup("4770 Lincoln");
$lookup->setMaxResults(10);
$lookup->setPreferStates(["IL"]);

$client->sendLookup($lookup);

Examine results

Results are attached to each lookup after sending.

US Street API results

foreach ($batch->getAllLookups() as $lookup) {
	echo "Results for: " . $lookup->getStreet() . PHP_EOL;

	foreach ($lookup->getResult() as $candidate) {
		echo "  Delivery line: " . $candidate->getDeliveryLine1() . PHP_EOL;
		echo "  Last line: " . $candidate->getLastLine() . PHP_EOL;
		echo "  Input ID: " . $candidate->getInputId() . PHP_EOL;
	}
}

US Autocomplete Pro results

foreach ($lookup->getResult() as $suggestion) {
	print_r($suggestion);
}

Error handling

All API errors throw a SmartyException:

use SmartyStreets\PhpSdk\Exceptions\SmartyException;

try {
	$client->sendLookup($lookup);
} catch (SmartyException $e) {
	echo "API error: " . $e->getMessage() . PHP_EOL;
}

More examples

Complete working examples are available in the GitHub repository:

• US Street API
• US Autocomplete Pro API
• US Enrichment API
• US Extract API
• US Reverse Geocoding API
• US ZIP Code API
• International Address Autocomplete API
• International Street API
• International Postal Code API

All PHP SDK examples are located in the examples/ directory of the official repository.