US Address Verification in iOS - Developer's quickstart guide
Welcome to the developer’s quickstart guide! This document will walk you through using the iOS SDK to access our US Address Verification product, but the same pattern applies to other Smarty products.
Before getting started, it’s important to note that most SDKs are hosted in Smarty’s official GitHub organization. The JavaScript SDK, Rust SDK, and some examples for TypeScript, React, and Vue can be found here. Also, if you’re working with another language, we’ve got support for that, too. These repositories also have examples of calling other Smarty APIs.
In-depth docs of other Smarty APIs can be found here.
Ready, set, let’s go!
Install
To get started with verifying US addresses, pull down Smarty’s iOS SDK to your development machine of choice. This is an example Package.swift file. Find the latest version at Smarty iOS SDK:
// swift-tools-version:5.9import PackageDescriptionlet package = Package( name: "samples", dependencies: [ .package(url: "https://github.com/smartystreets/smartystreets-ios-sdk.git", from: "11.2.0"), ], targets: [ .executableTarget( name: "swiftExamples", dependencies: [.product(name: "SmartyStreets", package: "smartystreets-ios-sdk")]), ])Quickstart
Import the Smarty SDK
Next, you’ll want to import the Smarty iOS SDK:
import Foundationimport SmartyStreetsThe SDK provides the structures and endpoints to access Smarty’s products.
Create an API client
Build your client object with your Smarty credentials (secret keys).
let authId = ProcessInfo.processInfo.environment["SMARTY_AUTH_ID"] ?? ""let authToken = ProcessInfo.processInfo.environment["SMARTY_AUTH_TOKEN"] ?? ""let client = ClientBuilder.withBasicAuth(authId: authId, authToken: authToken).buildUsStreetApiClient()This client handles all HTTP complexities. The ClientBuilder provides a number of option methods, such as setting max retries, timeouts, base URL, etc. For authentication, we will use basic auth with the secret keys. We recommend storing your credentials in environment variables for security.
Create and batch lookups
The Smarty iOS SDK sends all address validation requests in batches for us-street-api and us-zipcode-api. To create a request, start by creating a batch of addresses to send for processing at Smarty. We've provided some sample addresses here, but feel free to load your own addresses however you'd like.
let addresses = ["1600 Pennsylvania Avenue Washington, DC","1600 Amphitheatre Parkway Mountain View, CA 94043"]let batch = USStreetBatch()var error: NSError! = nilfor address in addresses { let lookup = USStreetLookup() lookup.street = address _ = batch.add(newAddress: lookup, error: &error)}Here, we’ve created a batch by loading each address into a Lookup object. Next, we add those Lookups to a Batch. Typically, these addresses come from a file, database, etc., but we’ve left that part up to you, depending on your needs.
For each lookup, you can use a combination of at least:
street, city, and state
ORstreet and ZIP Code
ORstreet(full address in a single field)
As another example, Lookup could include street, city, state, and ZIP Code, even though breaking the address into these components is not needed to perform the lookup.
let lookup = USStreetLookup()lookup.street = "1600 Amphitheatre Parkway"lookup.city = "Mountain View"lookup.state = "CA"lookup.zipCode = "94043"There are many other fields that allow you to customize your response, such as match type, candidates, inputID, etc. To explore all of these options, view the us-street-api documentation here.
Also note that each batch has a maximum size limit of 100; multiple concurrent batches can be sent.
Send batch
Once you have your Batch filled with Lookups, simply send the batch to get your validated results:
_ = client.sendBatch(batch: batch, error: &error)if let error = error { let output = """ Domain: \(error.domain) Error Code: \(error.code) Description:\n\(error.userInfo[NSLocalizedDescriptionKey] as! NSString) """ return output}To keep your integration reliable, we recommend handling any errors returned by the API. You can find a list of response codes for the us-street-api here.
Examine results
We’ve included a sample showing how you might loop through all results and print them, but at this point, you’re free to process the output however you like!
Keep in mind that each Lookup could have multiple results.
let lookups:[USStreetLookup] = batch.allLookups as! [USStreetLookup]var output = "Results\n"for i in 0..<batch.count() { let candidates:[USStreetCandidate] = lookups[i].result if candidates.count == 0 { output.append( "\nAddress \(i) is invalid\n") } for candidate in candidates { output.append(""" There is at least one candidate.\n If the match parameter is set to STRICT, the address is valid.\n Otherwise, check the Analysis output fields to see if the address is valid.\n\n \nZIP Code: \(candidate.components?.zipCode ?? "") \nCounty: \(candidate.metadata?.countyName ?? "") \nLatitude: \(candidate.metadata?.latitude ?? 0.0) \nLongitude: \(candidate.metadata?.longitude ?? 0.0) """) } output.append("\n*******************************************\n")}Documentation
Most of the SDKs are available in Smarty’s official GitHub organization, including the JavaScript SDK, Rust SDK, and repositories for TypeScript, React, and Vue. These repositories also have examples of calling other Smarty APIs.
In-depth docs for other Smarty APIs can be found here.
Was this helpful?