Submit US street addresses and get each one back as a row - resolved to a normalised address and coordinates, with Whitepages' resident and property columns alongside. This is a people-search source, so the rules that govern it are on this page rather than buried in a policy, and so is what our own test runs actually returned.
This section sits before everything else on purpose. A service that resolves who lives at an address carries obligations most scraping does not, and these restrictions are not house rules we invented - they are law where most of our customers operate.
Do not use this to decide employment, credit, insurance, housing or a tenant application. In the US those are regulated purposes that require a consumer reporting agency operating under the FCRA, and this is not one. No configuration of this service makes it one.
Do not use it to trace, doorstep, monitor or contact someone who has not asked to hear from you. Turning an address into a name is exactly the step that makes this category sensitive, and accounts doing it get closed.
Resolving a messy address column to a normalised address and coordinates is an ordinary data-quality task, and in our own runs it is the part that worked. If that is all you need, this service does it at 1,000 addresses a request.
When an address on an account you already hold looks inconsistent with what is publicly listed, checking it is a defensive use rather than an investigative one. That is a different activity from building a household directory, and only the first is in scope.
This is the single most important thing on the page, and burying it under a feature grid would be dishonest. Here is exactly what our own runs returned.
We hold four real exports of this service. Every one is a single row for a single address - the address the published reference uses as its own example, 321 California Ave, Palo Alto, CA 94306. In all four, the columns that carried a value were the address-resolution ones: address, lat, lon and matched_address, plus query and full_address in the wider shape. residents, residents_count, building_type and all twenty-three property_* columns were empty in every run.
The export told us why, in its own status column. Three runs returned “residents unavailable on free pool - needs residential proxy”; the fourth returned “no public residents”. Those are two different outcomes - one about how the request was routed, one about the address itself - and neither is a bug in your input. Read status on every row before you read anything else.
So the data dictionary below lists thirty-three column names taken byte-for-byte from the export header, and marks which six we have actually seen fill. The other twenty-seven are declared, not confirmed. We are not going to quote a hit rate for them, because one address is not a sample. Run a batch of your own on the free tier and look at the file before you plan anything around those columns.
A street address is the entire input. There are no filters to configure.
status column first.Write addresses the way you would type them into a search box - 321 California Ave, Palo Alto, CA 94306. The reference accepts arrays of up to 1,000 per request.
Every name below is copied byte-for-byte from the header row of our exports, in the order the spreadsheet emits them. The marking on each one says whether we have seen it carry a value.
status column for why.no public residents and residents unavailable on free pool - needs residential proxy.matched_address. Confirmed in the wide shape - the two carried identical values in every wide run.@context of the property record - the vocabulary the property_* columns are expressed in. Declared only.@type of the property record. Declared only.lat. Declared only.lon. Declared only.FTK for square foot or MTK for square metre. Read it before you compare two rows. Declared only.“Declared” means the export header names the column; it does not mean the column fills. Six of these thirty-three have carried a value in the runs we hold - address, lat, lon, matched_address, status and, in the wide shape, query and full_address. The rest were empty every time, across one address and four runs. That is far too little to express as a fill rate, so this table does not: it reports what we measured and stops there. Spend a few free-tier rows on addresses whose answers you already know before you build against any column marked declared.
Each of these came out of reading the exports rather than the reference, which is why they are worth the space.
Three of our four runs returned thirty-three columns. The fourth, and the oldest, returned six: address, lat, lon, matched_address, residents and status. Write the importer against those six and treat the other twenty-seven as present-if-present. A reader that assumes a fixed header will break the first time it meets the narrow shape.
Same thirty-three fields, two different orders. The spreadsheet opens with address, lat, lon, matched_address, residents, status and puts query seventh; the JSON puts those same six last, after every property_* field. Read columns by name. Anything that indexes by position will silently read the wrong field.
A lookup that finds no residents still returns a row, with the address resolved and the people columns blank. status is where the reason lives, and the two values we have seen mean different things: no public residents is about the address, while residents unavailable on free pool - needs residential proxy is about how the request was routed. Branch on that column rather than on whether residents is empty.
Their names are the Schema.org Accommodation and Place properties flattened with underscores - containedInPlace, floorSize with its value and unitCode, yearBuilt, geo with latitude and longitude. Useful to know when you map them: property_floor_size_unit_code carries a UN/CEFACT unit code, so floor areas are not necessarily in the same unit from row to row.
The uses below are the ones this service is for. The ones it is not for are at the top of the page, and they are not negotiable.
Addresses typed by humans arrive abbreviated, misspelled and inconsistently ordered. Submitting them here returns matched_address - one full postal form with street, neighbourhood, city, county, state, postcode and country - plus lat and lon. In our own runs this is the part that worked on every row.
Every resolved row carries latitude and longitude as strings, which is enough to plot a customer list, cluster a service area or join records to a territory. One request takes up to 1,000 addresses, so a large file is a handful of calls rather than a rate-limit problem.
When the address on an existing account looks inconsistent with what is publicly listed, resolving it tells you whether the discrepancy is a typo or something else. This is a defensive check on your own data - not a way to find out who lives somewhere, which is covered by the permitted uses above.
No subscription, no minimum, no per-seat licence. Your first 500 rows are on us - after that, pay-as-you-go.
Every new account, one-time. No credit card required. Given what the resident columns did in our runs, spending some of these on addresses you already know the answers for is the single most useful thing you can do first.
Roughly $2 per 1,000 addresses, one row per address - exact to budget, because an address that resolves to nothing still returns exactly one row.
Volume pricing, SLAs, dedicated workers and bespoke onboarding for teams re-checking a large address file on a schedule. Tell us your numbers and we'll quote.
LIVESCRAPER10 at checkout.Both of these sit in the same restricted category as this page, and the same permitted uses apply to them.
The same question put to a second source. Six columns rather than thirty-three, and its own honest account of what came back - worth reading next to this one.
The phone-number half of the same public-records family, with its own measured hit rate and the same restrictions. Use it when the identifier you hold is a number rather than an address.
Most pages in this catalogue describe facts about businesses or software. This one does not, and the difference is worth stating plainly rather than glossing.
Whitepages is a US directory that publishes contact and property information drawn from public records. The listings this service reads are the ones the site shows publicly - but the subject of those listings is a person, and that changes your obligations rather than ours. Under GDPR a household name and address is personal data whether or not it was easy to find, and in the US, using it for employment, credit, insurance or housing decisions is a regulated purpose this service is not licensed for.
The permitted uses at the top of this page are the short version. The longer version is that you need a lawful basis for holding these rows, a retention period you can defend, and an answer ready if the person asks you what you have. If any of those are missing, the right move is not to run the job.
On our side: publicly available sources only, no third-party trackers on the data layer, and your exports auto-delete after 30 days. We do not keep a copy of your results, and we do not build a database out of them.
The questions we hear most. Anything else? Talk to us - humans, not bots, write the answers.
residents and residents_count columns came back empty every time - with status reading no public residents once and residents unavailable on free pool - needs residential proxy the other three times. We publish the column names because the export header declares them; we are not going to claim a result we have not seen. Spend a few free rows on addresses you already know before you plan around those columns.address as you submitted it, lat and lon, matched_address normalised to a full postal form, status, and - in the wider shape - query and full_address. The address resolution worked on every row. The resident and property columns did not fill.address, lat, lon, matched_address, residents and status; the current one returns those plus twenty-seven more. Write your importer against the six and treat the rest as present-if-present rather than assuming a fixed header.query seventh, while the JSON puts those same six last, after every property_* field. Anything that indexes by position will read the wrong field on one of the two formats.Paste your addresses and get each one back normalised, geocoded and carrying its own status. Your first 500 rows are free - enough to see for yourself which columns fill for the addresses you care about.
Whitepages is a long-running US directory that publishes contact and property information compiled from public records, and its address pages are the part this service reads. The published reference describes the endpoint as returning insights about addresses and their residents, takes street addresses as its input - its own worked example is 321 California Ave, Palo Alto, CA 94306 - and accepts arrays of up to 1,000 addresses in a single request. Each address comes back as one row, so an input file and an output file line up exactly, including for addresses that resolve to nothing.
What that row contains is where this page differs from most product pages, because we are reporting measurements rather than intentions. Across four real exports the export header declared thirty-three columns, and six of them carried a value: the address exactly as submitted, latitude and longitude, a normalised matched address running from street through neighbourhood, city, county and state to postcode and country, a status column, and in the wider export shape the echoed query and a duplicate full address. The columns describing people and property - residents, residents count, building type, and the twenty-three property fields covering address, containing place, geo coordinates, floor size, year built, identifier and description - were empty in every run. The status column said why: three runs reported that residents were unavailable on the free pool and needed a residential proxy, and one reported no public residents at that address. We publish the column names because the export header declares them, and we mark the rest as declared rather than confirmed, because a header states what an export intends to contain and is not evidence that a column ever fills.
Three details matter to whoever writes the importer. There are two export shapes: an older six-column form and the current thirty-three-column form, so code against the six and treat the rest as optional. The JSON and the spreadsheet order the same fields differently - the spreadsheet leads with the six core columns while the JSON places them last, after the property fields - so columns must be read by name and never by position. And the property columns follow a public vocabulary rather than an invented one: their names are Schema.org Accommodation and Place properties flattened with underscores, which is why floor size arrives as a value plus a UN/CEFACT unit code that has to be read before two rows are compared.
This is a people-search source, and the obligations that come with it are set out at the top of the page rather than buried in a policy. It must not be used for employment, credit, insurance, housing or tenant decisions, which in the US are regulated purposes requiring a consumer reporting agency; and it must not be used to locate, approach or monitor a private individual. Cleaning an address column you already hold, geocoding a customer list, and verifying an address against your own records are the uses it is for, and address resolution is the part that worked on every row we ran. Publicly available sources only, no third-party trackers on the data layer, and exports auto-delete after 30 days. Your first 500 rows are free and need no credit card - spend some of them on addresses whose answers you already know.