Searching by Address

This guide walks through the best practices for using an address or location as an input parameter of a Search API query

Using the Address Parameters

The best way to include an address into an API query is to separate it into individual fields (house, street, city, state, country, zip_code). This ensures that the address is parsed correctly.

If it is not possible to separate the address into individual fields, there is also the option to use the raw address field to pass the full address. The Search API will do its best to interpret the address into the separate fields for the query. The address should be comma separated and follow the standard formatting of the country. If the address is outside of the US, you must include the two-digit country code at the end of the address for it to be parsed correctly. Check the query field in an API response to see how the API parsed your address and ensure that it was done correctly.

Below are some examples of addresses that can be parsed successfully by the Search API in the raw_address field:

  • 510 S Clearwater Loop, Post Falls, ID, 83854, US
  • 1600 Pennsylvania Avenue NW, Washington, DC 20500
  • 2 Gabriel Avenue, 75008 Paris, FR


Meeting Minimum Search Criteria

In the US, a full street address (down to the house number) can be searched by itself. Outside the US, you must include at least one other required parameter in order to fulfil the minimum requirements for a valid search

Partial Addresses

Even if you do not have the full street address of a person, if you are able to include location information in a query in the form of a partial address, this can significantly improve your results.

For example, if you are searching by a combination of name + email address, but you have information on the country of these individuals, consider adding this information into the query using the country field. If you have details of location down to the state or city level, this will likely improve the results even further.

Examples:[email protected]&country-US[email protected]&country-US&state=NY&city=New York City
fields = [Email(address='[email protected]'), Address(country='US', state='NY', city='New York City')]
request = SearchAPIRequest(person=Person(fields=fields), api_key='YOUR-API-KEY')