SmartyStreets Android SDK

If you want to access our US Street Address API or US ZIP Code API from an Android app, the SmartyStreets Java SDK can make it a lot easier. Although it is not specifically an Android SDK, it is fully supported in Android.

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 an Android app.
  2. Make sure you are using Android API Level 19 (KitKat) or higher as your target framework.
  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 install this SDK is by using Apache Maven through Android Studio.

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 for Android.

Verifying a Single US Street Address

package com.smartystreets.api.examples;

import com.smartystreets.api.Credentials;
import com.smartystreets.api.SharedCredentials;
import com.smartystreets.api.exceptions.SmartyException;
import com.smartystreets.api.us_street.Candidate;
import com.smartystreets.api.us_street.Client;
import com.smartystreets.api.us_street.ClientBuilder;
import com.smartystreets.api.us_street.Lookup;

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

public class UsStreetSingleAddressExample {

    public static String Run() {
        Credentials mobile = new SharedCredentials("SMARTY-WEBSITE-KEY", "HOST");
        Client client = new ClientBuilder(mobile).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();
        StringBuilder output = new StringBuilder();

        if (results.isEmpty()) {
            output.append("Error. Address is not valid.");
            return output.toString();
        }

        Candidate firstCandidate = results.get(0);

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

        return output.toString();
    }
}

Verifying Multiple US Street Addresses

package com.smartystreets.api.examples;

import com.smartystreets.api.Credentials;
import com.smartystreets.api.SharedCredentials;
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 UsStreetMultipleAddressesExample {
    public static String Run() {
        Credentials mobile = new SharedCredentials("SMARTY-WEBSITE-KEY", "HOST");
        Client client = new ClientBuilder(mobile).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("Error. Batch was already full.");
        }
        catch (SmartyException ex) {
            System.out.println(ex.getMessage());
            ex.printStackTrace();
        }
        catch (IOException ex) {
            ex.printStackTrace();
        }

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

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

            if (candidates.isEmpty()) {
                output.append("Address " + i + " is invalid.\n\n");
                continue;
            }

            output.append("Address " + i + " is valid. (There is at least one candidate)\n");

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

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

        return output.toString();
    }
}

Sending a Single Lookup to the US ZIP Code API

package com.smartystreets.api.examples;

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

import java.io.IOException;

public class UsZipCodeSingleLookupExample {
    public static String Run() {
        Credentials mobile = new SharedCredentials("SMARTY-WEBSITE-KEY", "HOST");
        Client client = new ClientBuilder(mobile).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();

        StringBuilder output = new StringBuilder();

        if (cities == null && zipCodes == null) {
            return output.append("Error getting cities and zip codes.").toString();
        }

        for (City city : cities) {
            output.append("\nCity: " + city.getCity() + "\n");
            output.append("State: " + city.getState() + "\n");
            output.append("Mailable City: " + city.getMailableCity() + "\n");
        }

        for (ZipCode zip : zipCodes) {
            output.append("\nZIP Code: " + zip.getZipCode() + "\n");
            output.append("Latitude: " + zip.getLatitude() + "\n");
            output.append("Longitude: " + zip.getLongitude() + "\n");
        }

        return output.toString();
    }
}

Sending Multiple Lookups to the US ZIP Code API

package com.smartystreets.api.examples;

import com.smartystreets.api.Credentials;
import com.smartystreets.api.SharedCredentials;
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 String Run() {
        Credentials mobile = new SharedCredentials("SMARTY-WEBSITE-KEY", "HOST");
        Client client = new ClientBuilder(mobile).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("Error. Batch was already full.");
        }
        catch (SmartyException ex) {
            System.out.println(ex.getMessage());
            ex.printStackTrace();
        }
        catch (IOException ex) {
            ex.printStackTrace();
        }

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

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

            if (result.getStatus() != null) {
                output.append("Status: " + result.getStatus() + "\n");
                output.append("Reason: " + result.getReason() + "\n");
                continue;
            }

            if (result.getCities() == null && result.getZipCodes() == null) {
                output.append("Error getting cities and zipcodes.\n\n");
                output.append("***************\n\n");
                continue;
            }

            City[] cities = result.getCities();
            output.append(cities.length + " City and State match(es):\n");

            for (City city : cities) {
                output.append("City: " + city.getCity() + "\n");
                output.append("State: " + city.getState() + "\n");
                output.append("Mailable City: " + city.getMailableCity() + "\n");
                output.append("\n");
            }

            ZipCode[] zipCodes = result.getZipCodes();
            output.append(zipCodes.length + " ZIP Code match(es):\n");

            for (ZipCode zipCode : zipCodes) {
                output.append("ZIP Code: " + zipCode.getZipCode() + "\n");
                output.append("County: " + zipCode.getCountyName() + "\n");
                output.append("Latitude: " + zipCode.getLatitude() + "\n");
                output.append("Longitude: " + zipCode.getLongitude() + "\n");
                output.append("\n");
            }
            output.append("***********************************\n");
        }

        return output.toString();
    }
}

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