Articles

 

Using SmartyStreets PHP SDK

This article is a companion to the YouTube video produced by SmartyStreets on how to use the SmartyStreets PHP SDK.

Its purpose it to show how to use the US Street API with a single address using PHP. Also see the Helpful Links section below for links to other APIs and examples.

SmartyStreets provides a PHP SDK to help with your development tasks.

In this article, we'll discuss:

Register

Before you can use the SmartyStreets PHP SDK, you will need to register for a free account. This will give you an auth-id and auth-token that you will use in the sample code below.

Once you register, login to your SmartyStreets Account.
Then click API Keys at the top of the page to find your auth-id and auth-token. These will be used in the sample code later in the article.

Install the SmartyStreets PHP SDK

Installation of the SDK can be done in ONE of two ways.

  1. Clone the SDK into the root of your project using:
    git clone git@github.com:smartystreets/smartystreets-php-sdk.git
    OR
  2. If you are using Composer, enter the following into composer.json for your project:
    "require": { "smartystreets/phpsdk": ">=4" }

US Street Single Address Sample Code

Note that this sample requires an auth-id and auth-token (see Register above).


<?php

require_once(dirname(__FILE__) . '/smartystreets-php-sdk/src/ClientBuilder.php');
require_once(dirname(__FILE__) . '/smartystreets-php-sdk/src/US_Street/Lookup.php');
require_once(dirname(__FILE__) . '/smartystreets-php-sdk/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() {
        $authId = '<your auth id here>';
        $authToken = '<your auth token here>';

        // We recommend storing your secret keys in environment variables instead---it's safer!
        // $authId = getenv('SMARTY_AUTH_ID');
        // $authToken = getenv('SMARTY_AUTH_TOKEN');

        $staticCredentials = new StaticCredentials($authId, $authToken);
        $client = (new ClientBuilder($staticCredentials))
                        // uncomment the following line to point to the specified proxy.
                        // ->viaProxy("http://localhost:8080", "username", "password") 
                        ->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("\nDelivery Address");
        echo("\n----------------");
        echo("\nDelivery line 1: " . $firstCandidate->getDeliveryLine1());
        echo("\nDelivery line 2: " . $firstCandidate->getDeliveryLine2());
        echo("\nLastline: " . $firstCandidate->getLastLine());

        echo("\n\nAddress Components");
        echo("\n------------------");       
        echo("\nPrimary Number: " . $firstCandidate->getComponents()->getPrimaryNumber());
        echo("\nStreet Name: " . $firstCandidate->getComponents()->getStreetName());
        echo("\nStreet Suffix: " . $firstCandidate->getComponents()->getStreetSuffix());
        echo("\nCity Name: " . $firstCandidate->getComponents()->getCityName());
        echo("\nZIP Code: " . $firstCandidate->getComponents()->getZIPCode());
        echo("\nCounty: " . $firstCandidate->getMetadata()->getCountyName());
        echo("\nLatitude: " . $firstCandidate->getMetadata()->getLatitude());
        echo("\nLongitude: " . $firstCandidate->getMetadata()->getLongitude());
    }
}
                    

Code Discussion

The require section may vary depending on where you have installed the PHP SDK. If the SDK root is in the same folder as your php source, the following will work, otherwise you may need to adjust the paths.


require_once(dirname(__FILE__) . '/smartystreets-php-sdk/src/ClientBuilder.php');
require_once(dirname(__FILE__) . '/smartystreets-php-sdk/src/US_Street/Lookup.php');
require_once(dirname(__FILE__) . '/smartystreets-php-sdk/src/StaticCredentials.php');
use SmartyStreets\PhpSdk\Exceptions\SmartyException;
use SmartyStreets\PhpSdk\StaticCredentials;
use SmartyStreets\PhpSdk\ClientBuilder;
use SmartyStreets\PhpSdk\US_Street\Lookup;
                    

Specify your AuthID and AuthToken that you received when you registered for a free SmartyStreets account. You can either hard-code the values, or create environment variables.

Next, you build the client object. If you have a proxy, uncomment out the viaProxy line and specify the URL and authentication if applicable.


$authId = '<your auth id here>';
$authToken = '<your auth token here>';

// We recommend storing your secret keys in environment variables instead---it's safer!
// $authId = getenv('SMARTY_AUTH_ID');
// $authToken = getenv('SMARTY_AUTH_TOKEN');

$staticCredentials = new StaticCredentials($authId, $authToken);
$client = (new ClientBuilder($staticCredentials))
                // uncomment the following line to point to the specified proxy.
                // ->viaProxy("http://localhost:8080", "username", "password")
                ->buildUsStreetApiClient();
                    

The Lookup object defines the data you want to use to perform the query. It can vary depending on the information you have available.

The next section of code performs the lookup and handles exceptions.

Note that this sample only performs a single query, however in other example code you will see how to perform multiple queries in a single API call.


$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());
}
                    

Lastly, we interpret the results from the API call in a function called displayResults(). Note that the results variable is an array which contains all possible candidates returned by the API. In this example, we just examine the first candidate.

Each candidate contains a summary for the USPS Delivery Address. You can also access the individual Address Components that are available for the address by using the getComponents() function on the candidate.

To see a complete list of the components, feel free to look in the SDK source code.


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("\nDelivery Address");
    echo("\n----------------");
    echo("\nDelivery line 1: " . $firstCandidate->getDeliveryLine1());
    echo("\nDelivery line 2: " . $firstCandidate->getDeliveryLine2());
    echo("\nLastline: " . $firstCandidate->getLastLine());

    echo("\n\nAddress Components");
    echo("\n------------------");
    echo("\nPrimary Number: " . $firstCandidate->getComponents()->getPrimaryNumber());
    echo("\nStreet Name: " . $firstCandidate->getComponents()->getStreetName());
    echo("\nStreet Suffix: " . $firstCandidate->getComponents()->getStreetSuffix());
    echo("\nCity Name: " . $firstCandidate->getComponents()->getCityName());
    echo("\nZIP Code: " . $firstCandidate->getComponents()->getZIPCode());
    echo("\nCounty: " . $firstCandidate->getMetadata()->getCountyName());
    echo("\nLatitude: " . $firstCandidate->getMetadata()->getLatitude());
    echo("\nLongitude: " . $firstCandidate->getMetadata()->getLongitude());
}
                    

Helpful PHP SDK Links

This site uses cookies for analytics, personalized content, and ads. By continuing to browse this site, you agree to this use.
Consuming raw or undercooked cookie dough may increase your risk of foodborne illness.