> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trestleiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reverse Address API

> Reverse Address API validates and normalizes input addresses while providing comprehensive insights into current residents' information, including demographics, historical addresses, relatives and associated people.

<Panel>
  <RequestExample>
    ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl --request GET \
      --url "https://api.trestleiq.com/3.1/location?address.street_line_1=100%20Main%20St&address.city=Seattle&address.state_code=WA&address.postal_code=98101" \
      --header "x-api-key: YOUR_API_KEY"
    ```

    ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const response = await fetch(
      "https://api.trestleiq.com/3.1/location?address.street_line_1=100%20Main%20St&address.city=Seattle&address.state_code=WA&address.postal_code=98101",
      {
        headers: {
          "x-api-key": "YOUR_API_KEY",
        },
      }
    );
    const data = await response.json();
    ```

    ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    import axios from "axios";

    const { data } = await axios.get(
      "https://api.trestleiq.com/3.1/location?address.street_line_1=100%20Main%20St&address.city=Seattle&address.state_code=WA&address.postal_code=98101",
      {
        headers: {
          "x-api-key": "YOUR_API_KEY",
        },
      }
    );
    console.log(data);
    ```

    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    import requests

    headers = {"x-api-key": "YOUR_API_KEY"}
    params = {
        "address.street_line_1": "100 Main St",
        "address.city": "Seattle",
        "address.state_code": "WA",
        "address.postal_code": "98101",
    }

    response = requests.get(
        "https://api.trestleiq.com/3.1/location",
        params=params,
        headers=headers,
        timeout=30,
    )
    data = response.json()
    print(data)
    ```

    ```csharp C# theme={"theme":{"light":"github-light","dark":"github-dark"}}
    using var client = new HttpClient();
    client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

    var response = await client.GetAsync("https://api.trestleiq.com/3.1/location?address.street_line_1=100%20Main%20St&address.city=Seattle&address.state_code=WA&address.postal_code=98101");
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
    ```

    ```go Go theme={"theme":{"light":"github-light","dark":"github-dark"}}
    package main

    import (
    	"fmt"
    	"io"
    	"net/http"
    )

    func main() {
    	req, _ := http.NewRequest("GET", "https://api.trestleiq.com/3.1/location?address.street_line_1=100%20Main%20St&address.city=Seattle&address.state_code=WA&address.postal_code=98101", nil)
    	req.Header.Set("x-api-key", "YOUR_API_KEY")

    	resp, err := http.DefaultClient.Do(req)
    	if err != nil {
    		panic(err)
    	}
    	defer resp.Body.Close()

    	body, _ := io.ReadAll(resp.Body)
    	fmt.Println(string(body))
    }
    ```

    ```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}}
    <?php
    $curl = curl_init("https://api.trestleiq.com/3.1/location?address.street_line_1=100%20Main%20St&address.city=Seattle&address.state_code=WA&address.postal_code=98101");
    curl_setopt($curl, CURLOPT_HTTPHEADER, ["x-api-key: YOUR_API_KEY"]);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($curl);
    curl_close($curl);

    echo $response;
    ```

    ```java Java theme={"theme":{"light":"github-light","dark":"github-dark"}}
    import java.net.URI;
    import java.net.http.HttpClient;
    import java.net.http.HttpRequest;
    import java.net.http.HttpResponse;

    public class ReverseAddressExample {
      public static void main(String[] args) throws Exception {
        HttpRequest request =
            HttpRequest.newBuilder()
                .uri(
                    URI.create(
                        "https://api.trestleiq.com/3.1/location?address.street_line_1=100%20Main%20St&address.city=Seattle&address.state_code=WA&address.postal_code=98101"))
                .header("x-api-key", "YOUR_API_KEY")
                .GET()
                .build();

        HttpResponse<String> response =
            HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
      }
    }
    ```
  </RequestExample>

  <ResponseExample>
    ```json Response Example theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "id": "Location.d1a40ed5-a70a-46f8-80a9-bb4ac27e3a01",
      "is_valid": true,
      "street_line_1": "100 Syrws St",
      "street_line_2": "Ste 1",
      "city": "Lynden",
      "postal_code": "98264",
      "zip4": "98264-9999",
      "state_code": "WA",
      "country_code": "US",
      "lat_long": {
        "latitude": 0,
        "longitude": 0,
        "accuracy": "Neighborhood"
      },
      "is_active": true,
      "is_commercial": true,
      "delivery_point": "SingleUnit",
      "current_residents": [
        {
          "id": "Person.fffdcf06-0929-4b5a-9921-ee49b101ca84",
          "name": "Waidong L Syrws",
          "firstname": "Waidong",
          "middlename": "L",
          "lastname": "Syrws",
          "alternate_names": [
            "Sryws W L"
          ],
          "age_range": "25-29",
          "gender": null,
          "type": "Person",
          "industry": null,
          "link_to_address_start_date": "2023-01-02",
          "historical_addresses": [
            {
              "id": "Location.d1a40ed5-a70a-46f8-80a9-bb4ac27e3a01",
              "location_type": "Address",
              "street_line_1": "10 Main St",
              "street_line_2": "Ste 1",
              "city": "Lynden",
              "postal_code": "98264",
              "zip4": "98264-9999",
              "state_code": "WA",
              "country_code": "US",
              "lat_long": {
                "latitude": 0,
                "longitude": 0,
                "accuracy": "Neighborhood"
              },
              "is_active": true,
              "delivery_point": "SingleUnit",
              "link_to_person_start_date": "2011-10-05",
              "link_to_person_end_date": null
            }
          ],
          "associated_people": [
            {
              "id": "Person.fffdcf06-0929-4b5a-9921-ee49b101ca84",
              "name": "Waidong L Syrws",
              "firstname": "Waidong",
              "middlename": "L",
              "lastname": "Syrws",
              "relation": "Household"
            }
          ]
        }
      ],
      "error": {
        "name": "InternalError",
        "message": "Could not retrieve entire response"
      },
      "warnings": [
        "Missing Input"
      ]
    }
    ```
  </ResponseExample>
</Panel>

## Reverse Address 3.1

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET https://api.trestleiq.com/3.1/location?api_key=[insert_key]&city=[insert_city]&postal_code=[insert_postal_code]&state_code=[insert_state_code]&street_line_1=[insert_street_line_1]
```

## Query Parameters

<ParamField query="street_line_1" type="string">
  The first line of the street part in the structured address. Cannot be longer than 1000 characters. **Example:** `street_line_1=100 Syrws St`
</ParamField>

<ParamField query="street_line_2" type="string">
  The second line of the street part in the structured address. Cannot be longer than 1000 characters. **Example:** `street_line_2=Ste 1`
</ParamField>

<ParamField query="city" type="string">
  The name of the city in the structured address. Cannot be longer than 500 characters. **Example:** `city=Seattle`
</ParamField>

<ParamField query="state_code" type="string">
  The state code of the structured address. Cannot be longer than 100 characters. **Example:** `state_code=WA`
</ParamField>

<ParamField query="postal_code" type="string">
  The postal code of the structured address. Cannot be longer than 100 characters. **Example:** `postal_code=98101`
</ParamField>

<ParamField query="country_code" type="string (ISO-3166-2)">
  The ISO-3166 alpha-2 country code of the address. Cannot be longer than 100 characters. **Example:** `country_code=US`
</ParamField>

## Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication. **Example:** `{{ apiKey }}`
</ParamField>

## Response

<ResponseField name="id" type="string or null <Location.<uuid>>">
  The persistent ID of the address.
</ResponseField>

<ResponseField name="is_valid" type="boolean or null">
  True if the address is valid.
</ResponseField>

<ResponseField name="street_line_1" type="string or null">
  The first line of the street part in the structured address.
</ResponseField>

<ResponseField name="street_line_2" type="string or null">
  The second line of the street part in the structured address.
</ResponseField>

<ResponseField name="city" type="string or null">
  The name of the city in the structured address.
</ResponseField>

<ResponseField name="postal_code" type="string or null">
  The postal code of the structured address.
</ResponseField>

<ResponseField name="state_code" type="string or null">
  The state code of the structured address.
</ResponseField>

<ResponseField name="zip4" type="string or null ^\d+-\d{4}$">
  The ZIP+4 code of the structured address (USA).
</ResponseField>

<ResponseField name="country_code" type="string or null (ISO-3166-2)">
  The ISO-3166 alpha-2 country code of the address.
</ResponseField>

<ResponseField name="lat_long" type="object or null">
  The coordinates of the geographical location of the address.

  <Expandable title="lat_long object">
    <ResponseField name="latitude" type="number or null <double>">
      The latitude coordinate of the location.
    </ResponseField>

    <ResponseField name="longitude" type="number or null <double>">
      The longitude coordinate of the location.
    </ResponseField>

    <ResponseField name="accuracy" type="string or null">
      The accuracy of the geographical location. Enum: <Badge>Country</Badge> <Badge>State</Badge> <Badge>City</Badge> <Badge>PostalCode</Badge> <Badge>Neighborhood</Badge> <Badge>Street</Badge> <Badge>RoofTop</Badge>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="is_active" type="boolean or null">
  True if the address is currently receiving mail.
</ResponseField>

<ResponseField name="is_commercial" type="boolean or null">
  True if the address is a business address.
</ResponseField>

<ResponseField name="delivery_point" type="string or null (DeliveryPoint)">
  The type of the delivery point of the address. Enum: <Badge>SingleUnit</Badge> <Badge>MultiUnit</Badge> <Badge>POBox</Badge> <Badge>PartialAddress</Badge>
</ResponseField>

<ResponseField name="current_residents" type="object[]">
  The list of current person and business residents at the address.

  <Expandable title="owner object">
    <ResponseField name="id" type="string or null <Person.<uuid>>">
      The persistent ID of the address.
    </ResponseField>

    <ResponseField name="name" type="string or null">
      The full name of the person.
    </ResponseField>

    <ResponseField name="firstname" type="string or null (FirstName)">
      The first name of the person.
    </ResponseField>

    <ResponseField name="middlename" type="string or null (MiddleName)">
      The middle name (or middle initial) of the person.
    </ResponseField>

    <ResponseField name="lastname" type="string or null (LastName)">
      The last name of the person.
    </ResponseField>

    <ResponseField name="alternate_names" type="string[]">
      Alternate names of the person associated with the phone.
    </ResponseField>

    <ResponseField name="age_range" type="string or null (AgeRange)">
      The age of the person in a 5-year range.
    </ResponseField>

    <ResponseField name="gender" type="string or null (Gender)">
      The gender of the person.
    </ResponseField>

    <ResponseField name="type" type="string">
      The type of the legal entity.

      * Person: The legal entity is a person.
      * Business: The legal entity is a company. \
        \
        Enum: <Badge>Person</Badge> <Badge>Business</Badge>
    </ResponseField>

    <ResponseField name="link_to_address_start_date" type="string or null">
      The date when the person was first linked to the address.
    </ResponseField>

    <ResponseField name="industry" type="string[] or null">
      The industry classification of the business associated to the phone.
    </ResponseField>

    <ResponseField name="historical_addresses" type="object[]">
      A list of historical addresses associated with the current resident of the input address.

      <Expandable title="address object">
        <ResponseField name="id" type="string or null <Location.<uuid>>">
          The persistent ID of the address.
        </ResponseField>

        <ResponseField name="location_type" type="string or null">
          The type of the location. Enum: <Badge>Country</Badge> <Badge>State</Badge> <Badge>City</Badge> <Badge>PostalCode</Badge> <Badge>ZipPlus4</Badge> <Badge>C</Badge> <Badge>Address</Badge>
        </ResponseField>

        <ResponseField name="street_line_1" type="string or null">
          The first line of the street part in the structured address.
        </ResponseField>

        <ResponseField name="street_line_2" type="string or null">
          The second line of the street part in the structured address.
        </ResponseField>

        <ResponseField name="city" type="string or null">
          The city associated with the address.
        </ResponseField>

        <ResponseField name="postal_code" type="string or null">
          The postal code of the structured address.
        </ResponseField>

        <ResponseField name="zip4" type="string or null ^\d+-\d{4}$">
          The ZIP+4 code of the structured address (USA).
        </ResponseField>

        <ResponseField name="state_code" type="string or null">
          The state code of the structured address.
        </ResponseField>

        <ResponseField name="country_code" type="string or null (ISO-3166-2)">
          The ISO-3166 alpha-2 country code of the phone number. See:[ISO-3166](https://www.nationsonline.org/oneworld/country_code_list.htm).
        </ResponseField>

        <ResponseField name="lat_long" type="object or null">
          The coordinates of the geographical location of the address.

          <Expandable title="lat_long object">
            <ResponseField name="latitude" type="number or null <double>">
              The latitude coordinate of the location.
            </ResponseField>

            <ResponseField name="longitude" type="number or null <double>">
              The longitude coordinate of the location.
            </ResponseField>

            <ResponseField name="accuracy" type="string or null">
              The accuracy of the geographical location. Enum: <Badge>Country</Badge> <Badge>State</Badge> <Badge>City</Badge> <Badge>PostalCode</Badge> <Badge>Neighborhood</Badge> <Badge>Street</Badge> <Badge>RoofTop</Badge>
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="is_active" type="boolean or null">
          True if the address is currently receiving mail.
        </ResponseField>

        <ResponseField name="delivery_point" type="string or null (DeliveryPoint)">
          The type of the delivery point of the address. Enum: <Badge>SingleUnit</Badge> <Badge>MultiUnit</Badge> <Badge>POBox</Badge> <Badge>PartialAddress</Badge>
        </ResponseField>

        <ResponseField name="link_to_person_start_date" type="string or null (LinkToPersonStartDate)">
          The date when the address was first linked to the person.
        </ResponseField>

        <ResponseField name="link_to_person_end_date" type="string or null">
          The date when the address was last linked to the person.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="associated_people" type="object[]">
      A list of people associated to the current home owner.

      <Expandable title="people object">
        <ResponseField name="id" type="string or null <Person.<uuid>>">
          The persistent ID of the person.
        </ResponseField>

        <ResponseField name="name" type="string or null">
          The full name of the associated person.
        </ResponseField>

        <ResponseField name="firstname" type="string or null">
          The first name of the associated person.
        </ResponseField>

        <ResponseField name="middlename" type="string or null">
          The middle name of the associated person.
        </ResponseField>

        <ResponseField name="lastname" type="string or null">
          The last name of the associated person.
        </ResponseField>

        <ResponseField name="relation" type="string or null">
          The relationship between the address owner and the associated person.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="object(PartialError)">
  Error details in case of an error.

  <Expandable title="error object">
    <ResponseField name="name" type="string">
      Incomplete response due to external timeouts. **value:** "InternalError"
    </ResponseField>

    <ResponseField name="message" type="string">
      The error message. **value:** "Could not retrieve entire response"
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="warnings" type="string[]">
  Warnings returned as part of the response, if applicable.\
  \
  Enum: <Badge>Invalid Address</Badge> <Badge>Missing Input</Badge> <Badge>Invalid house/building number</Badge> <Badge>Missing unit/apt/suite number</Badge> <Badge>Invalid unit/apt/suite number</Badge>
</ResponseField>

<Danger>
  ## Error Responses

  ### 400 Bad Request

  The server cannot process the request due to client-side errors.

  Check for: Syntax errors in the request script, malformed JSON, or invalid parameters.

  ### 403 Forbidden

  The request is understood, but the server is refusing to fulfill it. Error responses include an `errorCode` field identifying the cause:

  * **Invalid API Key** (`INVALID_API_KEY`): The key is incorrect, deactivated, or missing from the request.

    Check for: Trailing spaces, syntax errors, incorrect character counts, or a missing `x-api-key` header.

  * **API Key Disabled (Portal Issue)** (`FORBIDDEN`): The key is inactive.

    Check for: Insufficient funds in your self-serve wallet or if a Trestle Admin manually deactivated your API key.

  * **API Key does not have Product Access (Portal Issue)** (`FORBIDDEN`): The API key is active, but it is not enabled for this product or API version.

    Check for: Incorrect endpoint, incorrect API version, or missing product access on the key.

  * **API Key Expired** (`FORBIDDEN`): The key has reached its end-of-life (primarily affects Trial users).

  ### 429 Too Many Requests

  You have sent too many requests in a given amount of time.

  * **Rate Limit Exceeded** (`RATE_LIMIT_EXCEEDED`): You have surpassed the queries-per-second (QPS) threshold for your tier.

  * **Quota Exceeded (Portal Issue)** (`QUOTA_EXCEEDED`): You have reached the total volume allowed for your current billing cycle. Upgrade your plan in the portal to resume service.

  ### 500 Internal Server Error

  An unexpected error occurred on the server side. Please contact support if this persists.

  See [Error handling](/guides/errors) for all error response bodies and codes.
</Danger>