> ## 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.

# Address Validation API

> Address Validation API validates and normalizes US addresses, and provides valuable insights like latitude and longitude coordinates.

<Panel>
  <RequestExample>
    ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl --request GET \
      --url "https://api.trestleiq.com/3.0/location_intel?street_line_1=800%20Bellevue%20Way%20NE&city=Bellevue&state_code=WA&postal_code=98004" \
      --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.0/location_intel?street_line_1=800%20Bellevue%20Way%20NE&city=Bellevue&state_code=WA&postal_code=98004",
      {
        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.0/location_intel",
      {
        params: {
          street_line_1: "800 Bellevue Way NE",
          city: "Bellevue",
          state_code: "WA",
          postal_code: "98004",
        },
        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 = {
        "street_line_1": "800 Bellevue Way NE",
        "city": "Bellevue",
        "state_code": "WA",
        "postal_code": "98004",
    }

    response = requests.get(
        "https://api.trestleiq.com/3.0/location_intel",
        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.0/location_intel?street_line_1=800%20Bellevue%20Way%20NE&city=Bellevue&state_code=WA&postal_code=98004"
    );
    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"
    	"net/url"
    )

    func main() {
    	params := url.Values{}
    	params.Set("street_line_1", "800 Bellevue Way NE")
    	params.Set("city", "Bellevue")
    	params.Set("state_code", "WA")
    	params.Set("postal_code", "98004")

    	req, _ := http.NewRequest("GET", "https://api.trestleiq.com/3.0/location_intel?"+params.Encode(), 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
    $params = http_build_query([
      "street_line_1" => "800 Bellevue Way NE",
      "city"          => "Bellevue",
      "state_code"    => "WA",
      "postal_code"   => "98004",
    ]);

    $curl = curl_init("https://api.trestleiq.com/3.0/location_intel?" . $params);
    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 AddressValidationExample {
      public static void main(String[] args) throws Exception {
        HttpRequest request =
            HttpRequest.newBuilder()
                .uri(
                    URI.create(
                        "https://api.trestleiq.com/3.0/location_intel?street_line_1=800%20Bellevue%20Way%20NE&city=Bellevue&state_code=WA&postal_code=98004"))
                .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.6a3b1c11-76fd-4b25-86bc-5cfb588b4f6b",
      "is_valid": true,
      "street_line_1": "800 Bellevue Way NE",
      "street_line_2": null,
      "city": "Bellevue",
      "postal_code": "98004",
      "zip4": "4286",
      "state_code": "WA",
      "country_code": "US",
      "lat_long": {
        "latitude": 47.6175,
        "longitude": -122.2017,
        "accuracy": "RoofTop"
      },
      "error": null,
      "warnings": []
    }
    ```
  </ResponseExample>
</Panel>

## Address Validation API 3.0

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

<Warning>
  **Note:** This API supports US addresses only. Requests for non-US addresses will return a warning and no address data.
</Warning>

## Query Parameters

<ParamField query="street_line_1" type="string" required>
  The first line of the street part in the structured address. **Example:** `street_line_1=800 Bellevue Way NE`
</ParamField>

<ParamField query="street_line_2" type="string">
  The second line of the street part in the structured address (e.g. apartment or suite number). **Example:** `street_line_2=Ste 100`
</ParamField>

<ParamField query="city" type="string">
  The name of the city in the structured address. **Example:** `city=Bellevue`
</ParamField>

<ParamField query="state_code" type="string">
  The state code of the structured address. **Example:** `state_code=WA`
</ParamField>

<ParamField query="postal_code" type="string">
  The postal code of the structured address. **Example:** `postal_code=98004`
</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 validated address. Format: `Location.<uuid>`. Only present when the address is valid.
</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, normalized by USPS CASS standards.
</ResponseField>

<ResponseField name="street_line_2" type="string or null">
  The second line of the street part in the structured address. Returns `null` for this API — unit information is incorporated into `street_line_1` during normalization.
</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 5-digit postal code of the structured address.
</ResponseField>

<ResponseField name="zip4" type="string or null">
  The 4-digit ZIP+4 extension 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 address. Always `US` for valid responses from this API.
</ResponseField>

<ResponseField name="lat_long" type="object or null">
  The coordinates of the geographical location of the address. Only present when CASS returns coordinate data.

  <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 based on which address components were matched.

      Enum: <Badge>RoofTop</Badge> <Badge>PostalCode</Badge> <Badge>CityState</Badge> <Badge>State</Badge> <Badge>Country</Badge>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="string or null">
  An error message string if a partial error occurred during processing, otherwise `null`.
</ResponseField>

<ResponseField name="warnings" type="string[]">
  Warnings returned as part of the response, if applicable.

  Enum: <Badge>Missing Input</Badge> <Badge>Invalid address</Badge> <Badge>Invalid house/building number</Badge> <Badge>Missing unit/apt/suite number</Badge> <Badge>Invalid unit/apt/suite number</Badge> <Badge>Non-US country address validation is not supported.</Badge> <Badge>Address validation could not be completed at this time. Please try again later</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>