Address Verification API

Validate and standardize postal addresses to ensure deliverability and accuracy.

The Address Verification API validates, corrects, and standardizes postal addresses. This service helps ensure mail deliverability, reduce shipping errors, and maintain clean address data in your systems.

Endpoint

GET /api/v1/verify-address
POST /api/v1/verify-address

The address verification endpoint supports both GET and POST methods, allowing flexibility in how you submit address data.

Authentication

Requires API key authentication. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Request Parameters

GET Method

POST Method

For POST requests, send a JSON body:

{
  "address": "123 Main St, Anytown, USA"
}

You can also send structured address components:

{
  "street": "123 Main St",
  "city": "Anytown",
  "state": "CA",
  "postal_code": "12345"
}

Response Format

Success Response - Valid Address

{
  "verified_address": "123 MAIN ST, ANYTOWN NY 12345-6789",
  "status": "valid"
}

Success Response - Unverified Address

{
  "verified_address": "Unable to verify address",
  "status": "invalid"
}

Response Fields

Status Codes

• 200 OK: Address is valid and verified
• 422 Unprocessable Entity: Address is invalid or cannot be verified

Error Responses

Missing Required Parameter

{
  "error": {
    "code": 400,
    "message": "Address parameter is required"
  }
}

Status Code: 400 Bad Request

Invalid Request Format

{
  "error": {
    "code": 400,
    "message": "Invalid request format. Expected JSON body or query parameter."
  }
}

Status Code: 400 Bad Request

Insufficient Balance

{
  "error": {
    "code": 402,
    "message": "Insufficient balance. Please add funds to continue."
  }
}

Status Code: 402 Payment Required

Service Error

{
  "error": {
    "code": 500,
    "message": "Internal Server Error"
  }
}

Status Code: 500 Internal Server Error

Code Examples

cURL

GET Request

curl -X GET "https://core.streetverify.com/api/v1/verify-address?address=123%20Main%20St%2C%20Anytown%2C%20USA" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST Request

curl -X POST "https://core.streetverify.com/api/v1/verify-address" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "123 Main St, Anytown, USA"
  }'

JavaScript

class AddressVerifier {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://core.streetverify.com/api/v1';
  }

  async verify(address) {
    const params = new URLSearchParams({ address });
    
    const response = await fetch(`${this.baseUrl}/verify-address?${params}`, {
      headers: {
        'Authorization': `Bearer ${this.apiKey}`
      }
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error?.message || 'Verification failed');
    }

    return response.json();
  }

  async verifyAndCorrect(address) {
    const result = await this.verify(address);
    
    if (result.status === 'valid') {
      return {
        success: true,
        address: result.verified_address,
        status: result.status
      };
    } else {
      return {
        success: false,
        address: result.verified_address,
        status: result.status
      };
    }
  }
}

// Usage
const verifier = new AddressVerifier('YOUR_API_KEY');

try {
  const result = await verifier.verifyAndCorrect('123 main street anytown usa');
  
  if (result.success) {
    console.log('Verified address:', result.address);
    console.log('Status:', result.status);
  } else {
    console.log('Invalid address');
    console.log('Status:', result.status);
  }
} catch (error) {
  console.error('Verification error:', error.message);
}

Python

import requests
from typing import Dict, Optional

class AddressVerifier:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://core.streetverify.com/api/v1"
        
    def verify(self, address: str) -> Dict:
        """Verify an address and return the full response."""
        headers = {"Authorization": f"Bearer {self.api_key}"}
        params = {"address": address}
        
        response = requests.get(
            f"{self.base_url}/verify-address",
            params=params,
            headers=headers
        )
        response.raise_for_status()
        
        return response.json()
    
    def is_deliverable(self, address: str) -> bool:
        """Check if an address is deliverable."""
        result = self.verify(address)
        return result["status"] == "valid"
    
    def standardize(self, address: str) -> Optional[str]:
        """Get the standardized version of an address."""
        result = self.verify(address)
        
        if result["status"] == "valid":
            return result["verified_address"]
        else:
            return None

# Usage
verifier = AddressVerifier("YOUR_API_KEY")

# Simple verification
address = "123 Main St, Anytown, USA"
result = verifier.verify(address)

if result["status"] == "valid":
    print(f"Valid address: {result['verified_address']}")
else:
    print("Invalid address")
    print(f"Result: {result['verified_address']}")

React Component

import React, { useState } from 'react';

const AddressVerificationForm = ({ apiKey }) => {
  const [address, setAddress] = useState('');
  const [result, setResult] = useState(null);
  const [loading, setLoading] = useState(false);

  const verifyAddress = async () => {
    setLoading(true);
    try {
      const params = new URLSearchParams({ address });
      const response = await fetch(
        `https://core.streetverify.com/api/v1/verify-address?${params}`,
        {
          headers: {
            'Authorization': `Bearer ${apiKey}`
          }
        }
      );
      
      const data = await response.json();
      setResult(data);
    } catch (error) {
      setResult({ error: error.message });
    } finally {
      setLoading(false);
    }
  };

  return (
    <div className="address-verifier">
      <input
        type="text"
        value={address}
        onChange={(e) => setAddress(e.target.value)}
        placeholder="Enter address to verify"
        className="address-input"
      />
      
      <button onClick={verifyAddress} disabled={loading}>
        {loading ? 'Verifying...' : 'Verify Address'}
      </button>
      
      {result && !result.error && (
        <div className="result">
          {result.status === 'valid' ? (
            <div className="valid">
              <h3>✓ Valid Address</h3>
              <p>{result.verified_address}</p>
            </div>
          ) : (
            <div className="invalid">
              <h3>✗ Invalid Address</h3>
              <p>{result.verified_address}</p>
            </div>
          )}
        </div>
      )}
    </div>
  );
};

Use Cases

1. E-commerce Checkout Validation

Validate shipping addresses during checkout to prevent delivery failures:

const validateShippingAddress = async (orderData) => {
  const result = await verifier.verify(orderData.shippingAddress);
  
  if (result.status !== 'valid') {
    // Show error to customer
    return {
      valid: false,
      message: 'Please check your shipping address'
    };
  }
  
  // Update order with standardized address
  orderData.shippingAddress = result.verified_address;
  return { valid: true };
};

2. Database Cleanup

Standardize existing addresses in your database:

def cleanup_addresses(addresses):
    verifier = AddressVerifier(API_KEY)
    cleaned = []
    
    for addr in addresses:
        try:
            result = verifier.verify(addr['address'])
            if result['status'] == 'valid':
                addr['address'] = result['verified_address']
                addr['verified'] = True
            else:
                addr['verified'] = False
                addr['notes'] = 'Needs manual review'
            
            cleaned.append(addr)
        except Exception as e:
            addr['error'] = str(e)
            cleaned.append(addr)
    
    return cleaned

3. Address Form Auto-Correction

Provide real-time address correction as users type:

const AddressInput = () => {
  const [address, setAddress] = useState('');
  const [suggestion, setSuggestion] = useState('');
  const [debounceTimer, setDebounceTimer] = useState(null);

  const checkAddress = async (value) => {
    const result = await verifier.verify(value);
    
    if (result.status !== 'valid') {
      setSuggestion(result.verified_address);
    } else {
      setSuggestion('');
    }
  };

  const handleChange = (e) => {
    const value = e.target.value;
    setAddress(value);
    
    // Debounce API calls
    clearTimeout(debounceTimer);
    const timer = setTimeout(() => {
      if (value.length > 10) {
        checkAddress(value);
      }
    }, 500);
    setDebounceTimer(timer);
  };

  return (
    <div>
      <input
        value={address}
        onChange={handleChange}
        placeholder="Enter your address"
      />
      {suggestion && (
        <div className="suggestion" onClick={() => setAddress(suggestion)}>
          Did you mean: {suggestion}?
        </div>
      )}
    </div>
  );
};

Best Practices

1. Handle Invalid Addresses

When an address can’t be verified, provide clear feedback:

const handleInvalidAddress = (result) => {
  if (result.status === 'invalid') {
    // Address could not be verified
    return { 
      action: 'manual_review', 
      message: 'Please verify your address and try again'
    };
  } else {
    // Address is valid
    return { 
      action: 'proceed', 
      address: result.verified_address 
    };
  }
};

2. Address Validation in Forms

Validate addresses during form submission:

const validateAddressForm = async (formData) => {
  const result = await verifier.verify(formData.address);
  
  if (result.status !== 'valid') {
    return { 
      isValid: false, 
      error: 'Please enter a valid address' 
    };
  }
  
  // Update form with standardized address
  formData.address = result.verified_address;
  return { isValid: true };
};

3. Batch Processing

For multiple addresses, implement efficient batch processing:

const batchVerify = async (addresses, options = {}) => {
  const { 
    concurrency = 5,
    stopOnError = false,
    progressCallback 
  } = options;
  
  const results = [];
  const queue = [...addresses];
  let completed = 0;
  
  const processAddress = async (address) => {
    try {
      const result = await verifier.verify(address);
      return { address, result, error: null };
    } catch (error) {
      if (stopOnError) throw error;
      return { address, result: null, error: error.message };
    }
  };
  
  // Process in batches
  while (queue.length > 0) {
    const batch = queue.splice(0, concurrency);
    const batchResults = await Promise.all(
      batch.map(addr => processAddress(addr))
    );
    
    results.push(...batchResults);
    completed += batch.length;
    
    if (progressCallback) {
      progressCallback(completed, addresses.length);
    }
  }
  
  return results;
};

Rate Limits

All accounts operate on a pay-as-you-go model at $0.01 per request. Minimum credit purchase is $50 via crypto (USDT on Ethereum).

Related Endpoints

• Geocoding - Convert addresses to coordinates
• Autocomplete - Real-time address suggestions
• Reverse Geocoding - Convert coordinates to addresses