US Street Address Getting Started: Quickstart Guide (2026)

Getting started overview

This guide provides a step-by-step process for developers to begin using the US Street Address API. The primary objective is to enable quick integration for address validation, standardization, and geocoding. The API is designed to process US street addresses, offering capabilities for tasks such as e-commerce address verification, CRM data cleansing, shipping and logistics, and user input validation. Integration involves creating an account, obtaining API credentials, and making an initial API call.

The US Street Address API is a RESTful service, meaning it uses standard HTTP methods (like GET or POST) to interact with resources (addresses). Responses are typically formatted in JSON, a common data interchange format for web APIs (JSON:API specification). This approach allows for broad compatibility across various programming languages and platforms.

To ensure a smooth setup, the following steps will be covered:

• Account creation and API key retrieval.
• Making your first API request using common methods like cURL.
• Reviewing common next steps for further integration.
• Troubleshooting initial API calls.

Create an account and get keys

Accessing the US Street Address API requires an account and associated API credentials. These credentials typically consist of an Auth ID and an Auth Token, which are used to authenticate your requests.

1. Sign up for an account

Navigate to the US Street Address API homepage and initiate the sign-up process. A free tier is available, offering 250 lookups per month, which is suitable for initial testing and development purposes. Paid plans start at $25 for 10,000 lookups per month, providing scalability for higher usage volumes (Smarty address validation pricing).

2. Locate your API credentials

After creating and logging into your account, your API credentials (Auth ID and Auth Token) will be available in your account dashboard. These keys are unique to your account and must be kept secure, as they grant access to your API usage and associated billing.

3. Understand credential usage

The Auth ID and Auth Token are typically passed as query parameters in your API requests. For example, a request URL might include auth-id=YOUR_AUTH_ID&auth-token=YOUR_AUTH_TOKEN. It's important to use these correctly to avoid authentication errors.

Your first request

Once you have your Auth ID and Auth Token, you can make your first call to the US Street Address API. This example uses cURL, a command-line tool for making HTTP requests, which is widely available on most operating systems (cURL documentation).

Example: Validating a single US street address

The simplest way to validate an address is by sending a GET request with the address components as query parameters. Replace YOUR_AUTH_ID and YOUR_AUTH_TOKEN with your actual credentials.

curl -G "https://us-street.api.smarty.com/street-address"
  --data-urlencode "auth-id=YOUR_AUTH_ID"
  --data-urlencode "auth-token=YOUR_AUTH_TOKEN"
  --data-urlencode "street=1600 Amphitheatre Pkwy"
  --data-urlencode "city=Mountain View"
  --data-urlencode "state=CA"
  --data-urlencode "zipcode=94043"

In this example:

• -G tells cURL to send data as a GET request.
• --data-urlencode ensures that special characters in your address components are correctly encoded for the URL.
• The base API endpoint is https://us-street.api.smarty.com/street-address.
• The address components (street, city, state, zipcode) are provided as separate parameters.

Expected response format

A successful request will return a JSON array containing one or more address candidates. Each candidate includes standardized address components, delivery point information, and potentially geocoding data. For example, a response might look like this (abbreviated):

[
  {
    "input_index": 0,
    "candidate_index": 0,
    "delivery_line_1": "1600 Amphitheatre Pkwy",
    "last_line": "Mountain View CA 94043-1351",
    "components": {
      "primary_number": "1600",
      "street_name": "Amphitheatre",
      "street_suffix": "Pkwy",
      "city_name": "Mountain View",
      "state_abbreviation": "CA",
      "zipcode": "94043",
      "plus4_code": "1351",
      "delivery_point": "00",
      "delivery_point_check_digit": "4"
    },
    "metadata": {
      "record_type": "S",
      "zip_type": "Standard",
      "county_fips": "06085",
      "county_name": "Santa Clara",
      "latitude": 37.42777,
      "longitude": -122.0858,
      "precision": "Zip9",
      "time_zone": "Pacific",
      "utc_offset": -7,
      "dst": true
    },
    "analysis": {
      "dpv_match_code": "Y",
      "dpv_footnotes": "AABB",
      "dpv_cmra": "N",
      "dpv_vacant": "N",
      "dpv_no_stat": "N",
      "active": "Y"
    }
  }
]

This response indicates that the address was successfully validated and provides standardized components, a plus4_code, and geocoordinates (latitude and longitude). The analysis field provides details on the delivery point validation (DPV) status.

Using an SDK

For more complex applications, using one of the available SDKs (Python, JavaScript, PHP, Ruby, C#, Java, Go) is recommended. SDKs abstract the HTTP request details and provide language-specific objects and methods for easier interaction. Refer to the US Street Address API documentation for specific SDK examples.

Common next steps

After successfully making your first API call, consider these next steps for further integration and optimization:

• Batch Processing: For applications requiring validation of multiple addresses, the API supports batch processing. This allows you to send up to 100 addresses in a single request, reducing overhead and improving efficiency. This is particularly useful for CRM data cleansing or large database updates.
• Error Handling: Implement robust error handling in your application. The API returns specific HTTP status codes and error messages for issues such as invalid authentication, malformed requests, or rate limiting. Understanding these errors is crucial for stable integration.
• Advanced Features: Explore advanced features like providing secondary address unit information (apartments, suites) or utilizing the candidates parameter to request multiple potential matches for ambiguous addresses.
• Geocoding Integration: The API provides latitude and longitude coordinates in the response, enabling integration with mapping services like Google Maps Platform (Google Geocoding API overview) or ArcGIS Developers (ArcGIS Geocoding Service overview) for visualization or proximity searches.
• SDK Integration: If you started with cURL, consider transitioning to one of the official SDKs for your preferred programming language. SDKs often simplify request construction, response parsing, and error handling.
• Monitoring and Logging: Integrate API usage monitoring and logging into your application. This helps track usage, identify potential issues, and manage costs, especially when moving beyond the free tier.
• Security Best Practices: Always store your API keys securely, ideally using environment variables or a secret management service rather than hardcoding them into your application's source code.

Troubleshooting the first call

If your first API call does not return the expected results, consider the following common issues and troubleshooting steps:

• Authentication Errors (401 Unauthorized):
  • Issue: This usually means your Auth ID or Auth Token is incorrect or missing.
  • Solution: Double-check your credentials against those in your Smarty account dashboard. Ensure they are correctly included as auth-id and auth-token query parameters.
• Bad Request (400 Bad Request):
  • Issue: The request format is incorrect, or required parameters are missing.
  • Solution: Verify that all necessary address components (street, city, state, zipcode) are present and correctly spelled. Ensure that any special characters in the address are URL-encoded. Refer to the US Street Address API reference for required parameters.
• Rate Limit Exceeded (429 Too Many Requests):
  • Issue: You have sent too many requests in a short period, exceeding your plan's rate limit.
  • Solution: Implement exponential backoff or a similar retry strategy in your application. If this occurs frequently, consider upgrading your plan or optimizing your usage to reduce the number of calls.
• No Candidates in Response (Empty JSON Array):
  • Issue: The API could not find a valid match for the provided address.
  • Solution: This can happen with highly ambiguous or non-existent addresses. Check for typos in the address components. Try simplifying the address (e.g., removing apartment numbers) to see if a base street address can be validated.
• Network Connectivity Issues:
  • Issue: Your client (e.g., cURL) cannot reach the API endpoint.
  • Solution: Verify your internet connection. Check if the Smarty API endpoint (https://us-street.api.smarty.com) is accessible from your network.
• Incorrect URL:
  • Issue: The API endpoint URL is misspelled or incorrect.
  • Solution: Confirm you are using the correct endpoint: https://us-street.api.smarty.com/street-address.