LightBox Address Type Ahead

This sample demonstrates the LightBox Address Type Ahead feature. It includes a Jupyter Notebook walkthrough and a runnable Python script.

Jupyter Notebook

View Raw

LightBox API - Purpose of Autocomplete Endpoint

Return a set of address candidates based on autocompletion of the partial string 'text,' where each result includes a representative point for the address and references to related parcels. The '$ref' value within each 'parcels' object for a specific address can be used to get information about the parcel.

LightBox API - Geocoding Addresses with Autocomplete

This notebook demonstrates basic features of the LightBox Geocoding API by walking through the following steps:

  1. Import Python packages
  2. Enter your API Key for authorization
  3. Create request objects and display the results both in the JSON form.

Additional Materials: LightBox Developer Portal

#1. Import the required python packages

1import requests
2import json
3from typing import Dict

#2. Import function definitions

1# ----------------------------
2# Function Definitions
3# ----------------------------
4def autocomplete_address(
5        lightbox_api_key: str, 
6        address: str, 
7        country_code: str
8) -> Dict:
9    """
10    Autocompletes the provided address using the LightBox API.
11    
12    Args:
13        lightbox_api_key (str): The API key for accessing the LightBox API.
14        address (str): The partial address to be autocompleted.
15        country_code (str): The ISO 3166-1 alpha-2 country code.
16    
17    Returns:
18        dict: The autocompleted address information in JSON format.
19    """
20    # Prepare request parameters
21    BASE_URL = "https://api.lightboxre.com/v1"
22    ENDPOINT = "/addresses/_autocomplete"
23    URL = BASE_URL + ENDPOINT
24    params = {'text': address, 'countryCode': country_code}
25    headers = {'x-api-key': lightbox_api_key}
26
27    # Send request to LightBox API
28    response = requests.get(URL, params=params, headers=headers)
29
30    return response
31
32
33

#3. Create variables that will be used to authenticate your calls. Get your key from the LightBox Developer Portal.

1lightbox_api_key = '<YOUR_API_KEY>'

#4. LightBox Geocoding API Details This notbook will create various requests and display the output in JSON.

  1. Geocoding - https://api.lightboxre.com/addresses/_autocomplete

For additional details regarding each endpoint's request parameters or response models, visit the LightBox Geocoding on the LightBox Developer Portal page.

  1. Notice how the less the complete the address is, less options are provided by the API.
1address = '5201 C'
2country_code = 'US'
3address_search_data = autocomplete_address(lightbox_api_key, address, country_code)
4
5print(f"status_code: {address_search_data.status_code}")
6for address in address_search_data.json()["addresses"]:
7    print(address["label"])
status_code: 200
5201 AVENUE C, CORPUS CHRISTI, TX 78410-4720, US
5201 C ST, PHILADELPHIA, PA 19120-3608, US
5201 C ST, SACRAMENTO, CA 95819-2323, US
5201 C ST SE, WASHINGTON, DC 20019-6312, US
  1. Notice how the more the complete the address is, more options are provided by the API.
1address = '5201 California A'
2country_code = 'US'
3address_search_data = autocomplete_address(lightbox_api_key, address, country_code)
4
5print(f"status_code: {address_search_data.status_code}")
6for address in address_search_data.json()["addresses"]:
7    print(address["label"])
status_code: 200
5201 CALIFORNIA AVE UNIT A, IRVINE, CA 92617, US
5201 CALIFORNIA ST UNIT A, OMAHA, NE 68132, US
5201 CALIFORNIA AVE UNIT A, BAKERSFIELD, CA 93309, US
5201 S CALIFORNIA AVE UNIT A, CHICAGO, IL 60632, US
5201 CALIFORNIA AVE SW UNIT A, SEATTLE, WA 98136, US
5201 N CALIFORNIA AVE UNIT A, CHICAGO, IL 60625, US
5201 W CALIFORNIA RD UNIT A, FORT WAYNE, IN 46818, US
5201 CALIFORNINA ST, CARRABELLE, FL 32322, US
5201 W A ST, KERMAN, CA 93630, US
  1. Notice how if the address is limited, the API will not be able to match the input to an address
1address = '5401'
2country_code = 'US'
3address_search_data = autocomplete_address(lightbox_api_key, address, country_code)
4
5print(f"status_code: {address_search_data.status_code}")
6print(address_search_data.json())
status_code: 404
{'error': {'code': '404', 'message': 'Not Found'}}

Commonly Seen Errors

See LightBox Geocoder API for a list of common error responses.

Python Script

View Raw
1import requests
2import json
3from typing import Dict
4
5
6# ----------------------------
7# Function Definitions
8# ----------------------------
9def autocomplete_address(
10        lightbox_api_key: str, 
11        address: str, 
12        country_code: str
13) -> Dict:
14    """
15    Autocompletes the provided address using the LightBox API.
16    
17    Args:
18        lightbox_api_key (str): The API key for accessing the LightBox API.
19        address (str): The partial address to be autocompleted.
20        country_code (str): The ISO 3166-1 alpha-2 country code.
21    
22    Returns:
23        dict: The autocompleted address information in JSON format.
24    """
25    # Prepare request parameters
26    BASE_URL = "https://api.lightboxre.com/v1"
27    ENDPOINT = "/addresses/_autocomplete"
28    URL = BASE_URL + ENDPOINT
29    params = {'text': address, 'countryCode': country_code}
30    headers = {'x-api-key': lightbox_api_key}
31
32    # Send request to LightBox API
33    response = requests.get(URL, params=params, headers=headers)
34
35    return response
36
37
38def test_autocomplete_address_response_status(lightbox_api_key: str) -> None:
39    # Test case for successful request (HTTP status code 200)
40    address = '5201 California A'
41    country_code = 'US'
42    address_search_data = autocomplete_address(lightbox_api_key, address, country_code)
43    assert address_search_data.status_code == 200, f"Expected status code 200, but got {address_search_data.status_code}"
44
45    # Test case for unsuccessful request (HTTP status code 400)
46    address = '5201 California A'
47    country_code = 'U' # Invalid country_code
48    address_search_data = autocomplete_address(lightbox_api_key, address, country_code)
49    assert address_search_data.status_code == 400, f"Expected status code 400, but got {address_search_data.status_code}"
50
51    # Test case for unsuccessful request (HTTP status code 400)
52    address = '?' # Invalid address
53    country_code = 'US'
54    address_search_data = autocomplete_address(lightbox_api_key, address, country_code)
55    assert address_search_data.status_code == 400, f"Expected status code 400, but got {address_search_data.status_code}"
56
57    # Test case for unsuccessful request (HTTP status code 401)
58    address = '5201 California A'
59    country_code = 'US'
60    address_search_data = autocomplete_address(lightbox_api_key+"A", address, country_code) # Invalid API Key
61    assert address_search_data.status_code == 401, f"Expected status code 401, but got {address_search_data.status_code}"
62
63
64
65# ----------------------------
66# API Usage
67# ----------------------------
68lightbox_api_key = '<YOUR_API_KEY>'
69address = '5201 California A'
70country_code = 'US'
71
72address_search_data = autocomplete_address(lightbox_api_key, address, country_code)
73print(f"status_code: {address_search_data.status_code}")
74print(json.dumps(address_search_data.json(), indent=4))
75
76
77# ----------------------------
78# API Testing
79# ----------------------------
80test_autocomplete_address_response_status(lightbox_api_key)
81