Using Smarty PHP SDK
This article is a companion to the YouTube video produced by Smarty on how to use the Smarty 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.
Smarty provides a PHP SDK to help with your development tasks.
In this article, we'll discuss:
Register
Before you can use the Smarty PHP SDK, you will need to
register
for a free account. This will give you an and that you will use in
the sample
code below.
Once you register, login to your Smarty Account.
Then click API Keys at the top of the page to find your and .
These will be used in the sample code later in the article.
Install the Smarty PHP SDK
Installation of the SDK can be done in ONE of two ways.
- Clone the SDK into the root of your project using:
OR - If you are using Composer, enter the following into composer.json for your project:
US Street Single Address Sample Code
Note that this sample requires an and (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 Smarty
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 .
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
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