Documentation

 

SmartyStreets PHP SDK

If you want to access our US Street Address API or US ZIP Code API from an application written in the PHP programming language, the SmartyStreets PHP SDK can make it a lot easier. Our PHP SDK includes ready-made data structures and takes care of all the gritty, low-level HTTP intricacies for you.

Contents

  1. Requirements
  2. How to Get It
    1. Composer
    2. Download the Source Code
  3. How to Use It
    1. Demo
    2. Examples

Requirements

  1. Decide to build a software project using PHP.
  2. Download and install PHP 5.6 or higher.
  3. Build enough of the project to realize that you now need an address verification component.
  4. Wisely conclude that you don't want to build your own address verification component.
  5. Realize that SmartyStreets has already created an address verification component.
  6. Congratulations! You are now ready to use the SmartyStreets PHP SDK.

How to Get It

Composer

The easiest way to install this SDK is by using Composer.

Once you've downloaded Composer and initialized a composer.json file in your project, add

"require": {
    "smartystreets/phpsdk": "1.0.2"
}

to the "require" section. Of course, you can replace 1.0.2 with whatever version you want.

Download the Source Code

You can download the source code from the SmartyStreets PHP SDK repository on Github.

Use the source, Luke!

How to Use It

Demo

Examples

Here are a few pieces of example code to show how to use our PHP library/SDK.

Verifying a Single US Street Address

<?php

require_once('vendor/smartystreets/phpsdk/src/ClientBuilder.php');
require_once('vendor/smartystreets/phpsdk/src/us_street/Lookup.php');
require_once('vendor/smartystreets/phpsdk/src/StaticCredentials.php');
use SmartyStreets\PhpSdk\Exceptions\SmartyException;
use SmartyStreets\PhpSdk\StaticCredentials;
use SmartyStreets\PhpSdk\ClientBuilder;
use SmartyStreets\PhpSdk\US_Street\Lookup;

$lookupExample = new UsStreetSingleAddressExample();
$lookupExample->run();

class UsStreetSingleAddressExample {

    public function run() {
        $staticCredentials = new StaticCredentials(getenv('SMARTY_AUTH_ID'), getenv('SMARTY_AUTH_TOKEN'));
        $client = (new ClientBuilder($staticCredentials))->buildUsStreetApiClient();

        $lookup = new Lookup();
        $lookup->setStreet("1600 Amphitheatre Pkwy");
        $lookup->setCity("Mountain View");
        $lookup->setState("CA");

        try {
            $client->sendLookup($lookup);
            $this->displayResults($lookup);
        }
        catch (SmartyException $ex) {
            echo($ex->getMessage());
        }
        catch (\Exception $ex) {
            echo($ex->getMessage());
        }
    }

    public function displayResults(Lookup $lookup) {
        $results = $lookup->getResult();

        if (empty($results)) {
            echo("\nNo candidates. This means the address is not valid.");
            return;
        }

        $firstCandidate = $results[0];

        echo("\nAddress is valid. (There is at least one candidate)\n");
        echo("\nZIP Code: " . $firstCandidate->getComponents()->getZipCode());
        echo("\nCounty: " . $firstCandidate->getMetadata()->getCountyName());
        echo("\nLatitude: " . $firstCandidate->getMetadata()->getLatitude());
        echo("\nLongitude: " . $firstCandidate->getMetadata()->getLongitude());
    }
}

Verifying Multiple US Street Addresses

<?php

require_once('vendor/smartystreets/phpsdk/src/ClientBuilder.php');
require_once('vendor/smartystreets/phpsdk/src/us_street/Lookup.php');
require_once('vendor/smartystreets/phpsdk/src/StaticCredentials.php');
use SmartyStreets\PhpSdk\Exceptions\SmartyException;
use SmartyStreets\PhpSdk\Exceptions\BatchFullException;
use SmartyStreets\PhpSdk\StaticCredentials;
use SmartyStreets\PhpSdk\ClientBuilder;
use SmartyStreets\PhpSdk\US_Street\Lookup;
use SmartyStreets\PhpSdk\Batch;

$lookupExample = new UsStreetMultipleAddressesExample();
$lookupExample->run();

class UsStreetMultipleAddressesExample {
    public function run() {
        $staticCredentials = new StaticCredentials(getenv('SMARTY_AUTH_ID'), getenv('SMARTY_AUTH_TOKEN'));
        $client = (new ClientBuilder($staticCredentials))->buildUsStreetApiClient();
        $batch = new Batch();

        $address0 = new Lookup();
        $address0->setStreet("1600 amphitheatre parkway");
        $address0->setCity("Mountain view");
        $address0->setState("california");

        $address1 = new Lookup("1 Rosedale, Baltimore, Maryland"); // Freeform addresses work too.
        $address1->setMaxCandidates(10); // Allows up to ten possible matches to be returned (default is 1).

        $address2 = new Lookup("123 Bogus Street, Pretend Lake, Oklahoma");

        $address3 = new Lookup();
        $address3->setStreet("1 Infinite Loop");
        $address3->setZipCode("95014"); // You can just input the street and ZIP if you want.

        try {
            $batch->add($address0);
            $batch->add($address1);
            $batch->add($address2);
            $batch->add($address3);

            $client->sendBatch($batch);
            $this->displayResults($batch);
        }
        catch (BatchFullException $ex) {
            echo("Oops! Batch was already full.");
        }
        catch (SmartyException $ex) {
            echo($ex->getMessage());
        }
        catch (\Exception $ex) {
            echo($ex->getMessage());
        }
    }

    public function displayResults(Batch $batch) {
        $lookups = $batch->getAllLookups();

        for ($i = 0; $i < $batch->size(); $i++) {
            $candidates = $lookups[$i]->getResult();

            if (empty($candidates)) {
                echo("\nAddress " . $i . " is invalid.\n");
                continue;
            }

            echo("\nAddress " . $i . " is valid. (There is at least one candidate)");

            foreach ($candidates as $candidate) {
                $components = $candidate->getComponents();
                $metadata = $candidate->getMetadata();

                echo("\n\nCandidate " . $candidate->getCandidateIndex() . ":");
                echo("\nDelivery line 1: " . $candidate->getDeliveryLine1());
                echo("\nLast line:       " . $candidate->getLastLine());
                echo("\nZIP Code:        " . $components->getZipCode() . "-" . $components->getPlus4Code());
                echo("\nCounty:          " . $metadata->getCountyName());
                echo("\nLatitude:        " . $metadata->getLatitude());
                echo("\nLongitude:       " . $metadata->getLongitude());
            }
            echo("\n***********************************\n");
        }
        echo("\n");
    }
}

Sending a Single Lookup to the US ZIP Code API

<?php

require_once('vendor/smartystreets/phpsdk/src/ClientBuilder.php');
require_once('vendor/smartystreets/phpsdk/src/us_zipcode/Lookup.php');
require_once('vendor/smartystreets/phpsdk/src/us_zipcode/Result.php');
require_once('vendor/smartystreets/phpsdk/src/StaticCredentials.php');
require_once('vendor/smartystreets/phpsdk/src/SharedCredentials.php');
use SmartyStreets\PhpSdk\Exceptions\SmartyException;
use SmartyStreets\PhpSdk\StaticCredentials;
use SmartyStreets\PhpSdk\US_ZipCode\Lookup;
use SmartyStreets\PhpSdk\ClientBuilder;

$lookupExample = new UsZipCodeSingleLookupExample();
$lookupExample->run();

class UsZipCodeSingleLookupExample {

    public function run() {
        $staticCredentials = new StaticCredentials(getenv('SMARTY_AUTH_ID'), getenv('SMARTY_AUTH_TOKEN'));
        $client = (new ClientBuilder($staticCredentials))->buildUsZipCodeApiClient();

        $lookup = new Lookup();
        $lookup->setCity("Mountain View");
        $lookup->setState("California");

        try {
            $client->sendLookup($lookup);
            $this->displayResults($lookup);
        }
        catch (SmartyException $ex) {
            echo($ex->getMessage());
        }
        catch (\Exception $ex) {
            echo($ex->getMessage());
        }
    }

    public function displayResults(Lookup $lookup) {
        $result = $lookup->getResult();
        $zipCodes = $result->getZipCodes();
        $cities = $result->getCities();

        foreach ($cities as $city) {
            echo("\nCity: " . $city->getCity());
            echo("\nState: " . $city->getState());
            echo("\nMailable City: " . json_encode($city->getMailableCity()));
        }

        foreach ($zipCodes as $zip) {
            echo("\n\nZIP Code: " . $zip->getZipCode());
            echo("\nLatitude: " . $zip->getLatitude());
            echo("\nLongitude: " . $zip->getLongitude());
        }
    }
}

Sending Multiple Lookups to the US ZIP Code API

<?php

require_once('vendor/smartystreets/phpsdk/src/ClientBuilder.php');
require_once('vendor/smartystreets/phpsdk/src/us_zipcode/Lookup.php');
require_once('vendor/smartystreets/phpsdk/src/us_zipcode/Result.php');
require_once('vendor/smartystreets/phpsdk/src/StaticCredentials.php');
require_once('vendor/smartystreets/phpsdk/src/SharedCredentials.php');
use SmartyStreets\PhpSdk\Exceptions\SmartyException;
use SmartyStreets\PhpSdk\Exceptions\BatchFullException;
use SmartyStreets\PhpSdk\StaticCredentials;
use SmartyStreets\PhpSdk\US_ZipCode\Lookup;
use SmartyStreets\PhpSdk\ClientBuilder;
use SmartyStreets\PhpSdk\Batch;

$lookupExample = new UsZipCodeMultipleLookupsExample();
$lookupExample->run();

class UsZipCodeMultipleLookupsExample {

    public function run() {
        $staticCredentials = new StaticCredentials(getenv('SMARTY_AUTH_ID'), getenv('SMARTY_AUTH_TOKEN'));
        $client = (new ClientBuilder($staticCredentials))->buildUsZipCodeApiClient();
        $batch = new Batch();

        $lookup0 = new Lookup();
        $lookup0->setZipCode("12345");  // A Lookup may have a ZIP Code, city and state, or city, state, and ZIP Code

        $lookup1 = new Lookup();
        $lookup1->setCity("Phoenix");
        $lookup1->setState("Arizona");

        $lookup2 = new Lookup("cupertino", "CA", "95014"); // You can also set these with arguments

        try {
            $batch->add($lookup0);
            $batch->add($lookup1);
            $batch->add($lookup2);

            $client->sendBatch($batch);
            $this->displayResults($batch);
        }
        catch (BatchFullException $ex) {
            echo("Oops! Batch was already full.");
        }
        catch (SmartyException $ex) {
            echo($ex->getMessage());
        }
        catch (\Exception $ex) {
            echo($ex->getMessage());
        }
    }

    public function displayResults(Batch $batch) {
        $lookups = $batch->getAllLookups();

        for ($i = 0; $i < $batch->size(); $i++) {
            $result = $lookups[$i]->getResult();
            echo("\nLookup " . $i . ":\n");

            if ($result->getStatus() != null) {
                echo("Status: " . $result->getStatus());
                echo("Reason: " . $result->getReason());
                continue;
            }

            $cities = $result->getCities();
//            echo("\n");
            echo "\n" . count($cities) . " City and State match(es):";

            foreach ($cities as $city) {
                echo("\nCity: " . $city->getCity());
                echo("\nState: " . $city->getState());
                echo("\nMailable City: " . json_encode($city->getMailableCity()));
                echo("\n");
            }

            $zipCodes = $result->getZipCodes();
            echo "\n" . count($zipCodes) . " ZIP Code match(es):";

            foreach ($zipCodes as $zip) {
                echo("\nZIP Code: " . $zip->getZipCode());
                echo("\nCounty: " . $zip->getCountyName());
                echo("\nLatitude: " . $zip->getLatitude());
                echo("\nLongitude: " . $zip->getLongitude());
                echo("\n");
            }
            echo("\n***********************************");
        }
    }
}