Documentation

 

SmartyStreets Java SDK

If you want to access our APIs (other than the Download 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. Download the Source Code
  3. How to Use It
    1. Demo
    2. Verifying a Single US Street Address
    3. Verifying Multiple US Street Addresses
    4. Sending a Single Lookup to the US ZIP Code API
    5. Sending Multiple Lookups to the US ZIP Code API
    6. Sending the Beginning of an Address to the US Autocomplete API
    7. Sending Text to the US Extract API
    8. Verifying an International Street Address
  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.

Download the Source Code

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

Use the source, Luke!

How to Use It

Demo

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.StaticCredentials;
import com.smartystreets.api.exceptions.SmartyException;
import com.smartystreets.api.us_street.*;
import com.smartystreets.api.ClientBuilder;

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

public class UsStreetSingleAddressExample {
	public static void main(String[] args) {
		// We recommend storing your secret keys in environment variables.
		StaticCredentials credentials = new StaticCredentials(System.getenv("SMARTY_AUTH_ID"), System.getenv("SMARTY_AUTH_TOKEN"));
		Client client = new ClientBuilder(credentials)
// 				.withProxy(Proxy.Type.HTTP, "localhost", 8080) // Uncomment this line to try it with a proxy
				.buildUsStreetApiClient();

		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.StaticCredentials;
import com.smartystreets.api.exceptions.BatchFullException;
import com.smartystreets.api.exceptions.SmartyException;
import com.smartystreets.api.us_street.*;
import com.smartystreets.api.ClientBuilder;

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

public class UsStreetMultipleAddressesExample {
	public static void main(String[] args) {
		// We recommend storing your secret keys in environment variables.
		StaticCredentials credentials = new StaticCredentials(System.getenv("SMARTY_AUTH_ID"), System.getenv("SMARTY_AUTH_TOKEN"));
		Client client = new ClientBuilder(credentials).buildUsStreetApiClient();
		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.StaticCredentials;
import com.smartystreets.api.exceptions.SmartyException;
import com.smartystreets.api.us_zipcode.*;
import com.smartystreets.api.ClientBuilder;

import java.io.IOException;

public class UsZipCodeSingleLookupExample {
	public static void main(String[] args) {
		// We recommend storing your secret keys in environment variables.
		StaticCredentials credentials = new StaticCredentials(System.getenv("SMARTY_AUTH_ID"), System.getenv("SMARTY_AUTH_TOKEN"));
		Client client = new ClientBuilder(credentials).buildUsZipCodeApiClient();

		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 com.smartystreets.api.ClientBuilder;

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

public class UsZipCodeMultipleLookupsExample {
	public static void main(String[] args) {
		// We recommend storing your secret keys in environment variables.
		Client client = new ClientBuilder(System.getenv("SMARTY_AUTH_ID"), System.getenv("SMARTY_AUTH_TOKEN")).buildUsZipCodeApiClient();
		Batch batch = new Batch();

		Lookup lookup0 = new Lookup();
		lookup0.setZipCode("42223");   // 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());
				if (zipCode.getAlternateCounties() != null)
					System.out.println("First alternate county: " + zipCode.getAlternateCounty(0).getCountyName());
				System.out.println("Latitude: " + zipCode.getLatitude());
				System.out.println("Longitude: " + zipCode.getLongitude());
				System.out.println();
			}
			System.out.println("***********************************");
		}
	}
}

Sending the Beginning of an Address to the US Autocomplete API

package examples;

import com.smartystreets.api.StaticCredentials;
import com.smartystreets.api.exceptions.SmartyException;
import com.smartystreets.api.us_autocomplete.*;
import com.smartystreets.api.ClientBuilder;

import java.io.IOException;

public class UsAutocompleteExample {
	public static void main(String[] args) throws IOException, SmartyException {
		// We recommend storing your secret keys in environment variables.
		StaticCredentials credentials = new StaticCredentials(System.getenv("SMARTY_AUTH_ID"), System.getenv("SMARTY_AUTH_TOKEN"));
		Client client = new ClientBuilder(credentials).buildUsAutocompleteApiClient();
		Lookup lookup = new Lookup("4770 Lincoln Ave O");

		client.send(lookup);

		System.out.println("*** Result with no filter ***");
		System.out.println();
		for (Suggestion suggestion : lookup.getResult()) {
			System.out.println(suggestion.getText());
		}

		lookup.addStateFilter("IL");
		lookup.setMaxSuggestions(5);

		Suggestion[] suggestions = client.send(lookup); // The client will also return the suggestions directly

		System.out.println();
		System.out.println("*** Result with some filters ***");
		for (Suggestion suggestion : suggestions) {
			System.out.println(suggestion.getText());
		}
	}
}

Sending Text to the US Extract API

package examples;

import com.smartystreets.api.ClientBuilder;
import com.smartystreets.api.StaticCredentials;
import com.smartystreets.api.exceptions.SmartyException;
import com.smartystreets.api.us_extract.*;
import com.smartystreets.api.us_street.Candidate;

import java.io.IOException;

public class UsExtractExample {
	public static void main(String[] args) throws IOException, SmartyException {
		// We recommend storing your secret keys in environment variables.
		StaticCredentials credentials = new StaticCredentials(System.getenv("SMARTY_AUTH_ID"), System.getenv("SMARTY_AUTH_TOKEN"));
		Client client = new ClientBuilder(credentials).buildUsExtractApiClient();
		String text = "Here is some text.\r\nMy address is 3785 Las Vegs Av." +
				"\r\nLos Vegas, Nevada." +
				"\r\nMeet me at 1 Rosedale Baltimore Maryland, not at 123 Phony Street, Boise Idaho.";
		Lookup lookup = new Lookup(text);

		Result result = client.send(lookup);

		Metadata metadata = result.getMetadata();
		System.out.println("Found " + metadata.getAddressCount() + " addresses.");
		System.out.println(metadata.getVerifiedCount() + " of them were valid.");
		System.out.println();

		Address[] addresses = result.getAddresses();

		System.out.println("Addresses: \r\n**********************\r\n");
		for (Address address : addresses) {
			System.out.println("\"" + address.getText() + "\"\n");
			System.out.println("Verified? " + address.isVerified());
			if (address.getCandidates().length > 0) {
				System.out.println("\nMatches:");

				for (Candidate candidate : address.getCandidates()) {
					System.out.println(candidate.getDeliveryLine1());
					System.out.println(candidate.getLastLine());
					System.out.println();
				}
			} else System.out.println();

			System.out.println("**********************\n");
		}
	}
}

Verifying an International Street Address

package examples;

import com.smartystreets.api.ClientBuilder;
import com.smartystreets.api.StaticCredentials;
import com.smartystreets.api.exceptions.SmartyException;
import com.smartystreets.api.international_street.*;

import java.io.IOException;

public class InternationalExample {
	public static void main(String[] args) throws IOException, SmartyException {
		// We recommend storing your secret keys in environment variables.
		StaticCredentials credentials = new StaticCredentials(System.getenv("SMARTY_AUTH_ID"), System.getenv("SMARTY_AUTH_TOKEN"));
		Client client = new ClientBuilder(credentials).buildInternationalStreetApiClient();

		Lookup lookup = new Lookup("Rua Padre Antonio D'Angelo 121 Casa Verde, Sao Paulo", "Brazil");
		lookup.setGeocode(true); // Must be expressly set to get latitude and longitude.

		Candidate[] candidates = client.send(lookup); // The candidates are also stored in the lookup's 'result' field.

		Candidate firstCandidate = candidates[0];
		System.out.println("Address is " + firstCandidate.getAnalysis().getVerificationStatus());
		System.out.println("Address precision: " + firstCandidate.getAnalysis().getAddressPrecision() + "\n");

		System.out.println("First Line: " + firstCandidate.getAddress1());
		System.out.println("Second Line: " + firstCandidate.getAddress2());
		System.out.println("Third Line: " + firstCandidate.getAddress3());
		System.out.println("Fourth Line: " + firstCandidate.getAddress4());
		System.out.println("Latitude: " + firstCandidate.getMetadata().getLatitude());
		System.out.println("Longitude: " + firstCandidate.getMetadata().getLongitude());
	}
}