Search by Address

Use address parameters to find people associated with a specific location. By default, searches match only current addresses. Enable include_historical_locations to also search historical addresses.

Basic Usage

Search for people at a specific address:

Request

curl 'https://api.whitepages.com/v2/person?street=123%20Main%20St&city=Seattle&state_code=WA' \
  --header 'X-Api-Key: YOUR_API_KEY'

This returns people whose current address matches the search criteria.

Include Historical Addresses

To search both current and historical addresses, set include_historical_locations=true:

Request

curl 'https://api.whitepages.com/v2/person?street=123%20Main%20St&city=Seattle&state_code=WA&include_historical_locations=true' \
  --header 'X-Api-Key: YOUR_API_KEY'

This returns people who currently live at the address or have previously lived there.

Parameters

Parameter	Type	Default	Description
`street`	string	—	Street address
`city`	string	—	City name
`state_code`	string	—	Two-letter state code
`zipcode`	string	—	ZIP code
`include_historical_locations`	boolean	`false`	Include historical addresses in search

Examples

Search by ZIP Code Only

Find people in a specific ZIP code:

curl 'https://api.whitepages.com/v2/person?zipcode=98101' \
  --header 'X-Api-Key: YOUR_API_KEY'

Search by City and State

Find people in a specific city:

curl 'https://api.whitepages.com/v2/person?city=Portland&state_code=OR' \
  --header 'X-Api-Key: YOUR_API_KEY'

Find Previous Residents

Find anyone who has ever lived at an address:

curl 'https://api.whitepages.com/v2/person?street=456%20Oak%20Ave&city=Denver&state_code=CO&zipcode=80202&include_historical_locations=true' \
  --header 'X-Api-Key: YOUR_API_KEY'

Combine with Name Search

Find a specific person at an address:

curl 'https://api.whitepages.com/v2/person?name=John%20Smith&street=789%20Pine%20St&city=Austin&state_code=TX&include_historical_locations=true' \
  --header 'X-Api-Key: YOUR_API_KEY'

Historical Address Coverage

Historical address data varies by record. Some individuals may have extensive address history while others may only have current address information available.

Response

The response includes both current and historical addresses for each person found:

Response

[
  {
    "id": "P1234567890",
    "name": "John Smith",
    "aliases": ["Johnny Smith"],
    "is_dead": false,
    "current_addresses": [
      { "id": "A9876543210", "address": "123 Main St, Seattle, WA 98101" }
    ],
    "historic_addresses": [
      { "id": "A1234567890", "address": "456 Oak Ave, Portland, OR 97201" },
      { "id": "A2345678901", "address": "789 Pine St, San Francisco, CA 94102" }
    ],
    "owned_properties": [
      { "id": "R5432109876", "address": "123 Main St, Seattle, WA 98101" }
    ],
    "phones": [{ "number": "(206) 555-0198", "type": "mobile", "score": 92 }],
    "emails": [{ "address": "john.smith@example.com", "score": 88 }],
    "date_of_birth": "1985-03-15",
    "linkedin_url": "https://linkedin.com/in/johnsmith",
    "company_name": "Acme Corp",
    "job_title": "Software Engineer",
    "relatives": [{ "id": "P0987654321", "name": "Jane Smith" }]
  }
]

Current vs Historical

When include_historical_locations=true, the search matches against both current_addresses and historic_addresses. The response always includes both fields regardless of the search setting.

Address Standardization (CASS)

Person addresses in the Whitepages dataset are processed through CASS certification (Coding Accuracy Support System), the USPS address standardization program. All addresses are run through SmartyStreets to normalize formatting and assign a validity status before being stored.

This means:

Addresses are in a consistent format regardless of how they were originally recorded
Every address has a validity status indicating how well it was verified

Validity Status

Status	Description
`valid`	Address fully verified and deliverable
`missing_secondary`	Valid street address but missing a unit or apartment number
`invalid_secondary`	Unit or apartment number provided but does not match records
`invalid_primary`	Street number could not be confirmed
`invalid`	Address could not be verified

Addresses with a non-valid status are still included in results. For example, missing_secondary addresses are real, occupied locations that simply lack a unit identifier in the data — they are not excluded.

On this page