SmartyStreets Java SDK

If you want to access our US Street Address API or US ZIP Code API from a Java application, the SmartyStreets Java SDK can make it a lot easier. Our Java 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. Maven
    2. Downloading the JAR File
  3. How to Use It
    1. Verifying a Single US Street Address
    2. Verifying Multiple US Street Addresses
    3. Sending a Single Lookup to the US ZIP Code API
    4. Sending Multiple Lookups to the US ZIP Code API
  4. API Reference Material

Requirements

  1. Decide to build a software project using Java.
  2. Download and install Java 7 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 Java SDK.

How to Get It

Maven

The easiest way to get your giddy hands on this goodness is by using Apache Maven.
Just pop open your project's pom.xml file, and add

<dependency>
    <groupId>com.smartystreets.api</groupId>
    <artifactId>smartystreets-java-sdk</artifactId>
    <version>1.0.4</version>
</dependency>

to the <dependencies> section. Of course, you can replace 1.0.4 with whatever version you want.

Downloading the JAR File

You can download the JAR from this page.

How to Use It

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

Verifying a Single US Street Address

package examples;

import com.smartystreets.api.exceptions.SmartyException;
import com.smartystreets.api.us_street.*;

import java.io.IOException;
import java.util.ArrayList;

public class UsStreetSingleAddressExample {
    public static void main(String[] args) {
        Client client = new ClientBuilder("YOUR AUTH-ID HERE", "YOUR AUTH-TOKEN HERE").build();

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

        try {
            client.send(lookup);
        }
        catch (SmartyException ex) {
            System.out.println(ex.getMessage());
            ex.printStackTrace();
        }
        catch (IOException ex) {
            ex.printStackTrace();
        }

        ArrayList<Candidate> results = lookup.getResult();

        if (results.isEmpty()) {
            System.out.println("No candidates. This means the address is not valid.");
            return;
        }

        Candidate firstCandidate = results.get(0);

        System.out.println("Address is valid. (There is at least one candidate)\n");
        System.out.println("ZIP Code: " + firstCandidate.getComponents().getZipCode());
        System.out.println("County: " + firstCandidate.getMetadata().getCountyName());
        System.out.println("Latitude: " + firstCandidate.getMetadata().getLatitude());
        System.out.println("Longitude: " + firstCandidate.getMetadata().getLongitude());
    }
}

Verifying Multiple US Street Addresses

package examples;

import com.smartystreets.api.exceptions.BatchFullException;
import com.smartystreets.api.exceptions.SmartyException;
import com.smartystreets.api.us_street.*;

import java.io.IOException;
import java.util.ArrayList;
import java.util.Vector;

public class UsStreetMultipleAddressExample {
    public static void main(String[] args) {
        Client client = new ClientBuilder("YOUR AUTH-ID HERE", "YOUR AUTH-TOKEN HERE").build();
        Batch batch = new Batch();

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

        Lookup 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).

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

        Lookup 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.send(batch);
        }
        catch(BatchFullException ex) {
            System.out.println("Oops! Batch was already full.");
        }
        catch (SmartyException ex) {
            System.out.println(ex.getMessage());
            ex.printStackTrace();
        }
        catch (IOException ex) {
            ex.printStackTrace();
        }

        Vector<Lookup> lookups = batch.getAllLookups();

        for (int i=0; i < batch.size(); i++) {
            ArrayList<Candidate> candidates = lookups.get(i).getResult();

            if (candidates.isEmpty()) {
                System.out.println("Address " + i + " is invalid.\n");
                continue;
            }

            System.out.println("Address " + i + " is valid. (There is at least one candidate)");

            for (Candidate candidate : candidates){
                final Components components = candidate.getComponents();
                final Metadata metadata = candidate.getMetadata();

                System.out.println("\nCandidate " + candidate.getCandidateIndex() + ":");
                System.out.println("Delivery line 1: " + candidate.getDeliveryLine1());
                System.out.println("Last line:       " + candidate.getLastLine());
                System.out.println("ZIP Code:        " + components.getZipCode() + "-" + components.getPlus4Code());
                System.out.println("County:          " + metadata.getCountyName());
                System.out.println("Latitude:        " + metadata.getLatitude());
                System.out.println("Longitude:       " + metadata.getLongitude());
            }
            System.out.println();
        }
    }
}

Sending a Single Lookup to the US ZIP Code API

package examples;

import com.smartystreets.api.exceptions.SmartyException;
import com.smartystreets.api.us_zipcode.*;

import java.io.IOException;

public class UsZipCodeSingleLookupExample {
    public static void main(String[] args) {
        Client client = new ClientBuilder("YOUR AUTH-ID HERE", "YOUR AUTH-TOKEN HERE").build();

        Lookup lookup = new Lookup();
        lookup.setCity("Mountain View");
        lookup.setState("California");

        try {
            client.send(lookup);
        }
        catch (SmartyException ex) {
            System.out.println(ex.getMessage());
            ex.printStackTrace();
        }
        catch (IOException ex) {
            ex.printStackTrace();
        }

        Result result = lookup.getResult();
        ZipCode[] zipCodes = result.getZipCodes();
        City[] cities = result.getCities();

        for (City city : cities) {
            System.out.println("\nCity: " + city.getCity());
            System.out.println("State: " + city.getState());
            System.out.println("Mailable City: " + city.getMailableCity());
        }

        for (ZipCode zip : zipCodes) {
            System.out.println("\nZIP Code: " + zip.getZipCode());
            System.out.println("Latitude: " + zip.getLatitude());
            System.out.println("Longitude: " + zip.getLongitude());
        }
    }
}

Sending Multiple Lookups to the US ZIP Code API

package examples;

import com.smartystreets.api.exceptions.BatchFullException;
import com.smartystreets.api.exceptions.SmartyException;
import com.smartystreets.api.us_zipcode.*;

import java.io.IOException;
import java.util.Vector;

public class UsZipCodeMultipleLookupsExample {
    public static void main(String[] args) {
        Client client = new ClientBuilder("YOUR AUTH-ID HERE", "YOUR AUTH-TOKEN HERE").build();
        Batch batch = new Batch();

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

        Lookup lookup1 = new Lookup();
        lookup1.setCity("Phoenix");
        lookup1.setState("Arizona");

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

        try{
            batch.add(lookup0);
            batch.add(lookup1);
            batch.add(lookup2);

            client.send(batch);
        }
        catch(BatchFullException ex) {
            System.out.println("Oops! Batch was already full.");
        }
        catch (SmartyException ex) {
            System.out.println(ex.getMessage());
            ex.printStackTrace();
        }
        catch (IOException ex) {
            ex.printStackTrace();
        }

        Vector<Lookup> lookups = batch.getAllLookups();

        for (int i=0; i < batch.size(); i++) {
            Result result = lookups.get(i).getResult();
            System.out.println("Lookup " + i + ":\n");

            if (result.getStatus() != null) {
                System.out.println("Status: " + result.getStatus());
                System.out.println("Reason: " + result.getReason());
                continue;
            }

            City[] cities = result.getCities();
            System.out.println(cities.length + " City and State match(es):");

            for (City city : cities) {
                System.out.println("City: " + city.getCity());
                System.out.println("State: " + city.getState());
                System.out.println("Mailable City: " + city.getMailableCity());
                System.out.println();
            }

            ZipCode[] zipCodes = result.getZipCodes();
            System.out.println(zipCodes.length + " ZIP Code match(es):");

            for (ZipCode zipCode : zipCodes) {
                System.out.println("ZIP Code: " + zipCode.getZipCode());
                System.out.println("County: " + zipCode.getCountyName());
                System.out.println("Latitude: " + zipCode.getLatitude());
                System.out.println("Longitude: " + zipCode.getLongitude());
                System.out.println();
            }
            System.out.println("***********************************");
        }
    }
}

Product Features Demo Pricing Help Company Documentation Articles Contact Customers Legal Stuff