### Use CensusGeocode Command-Line Interface

Source: https://context7.com/fitnr/censusgeocode/llms.txt

Provides examples for using the CLI tool to geocode single addresses or batch files, including options for custom benchmarks, timeouts, and return types.

```bash
censusgeocode '1600 Pennsylvania Avenue, Washington DC'
censusgeocode --csv addresses.csv --rettype geographies
censusgeocode '1600 Pennsylvania Ave, Washington, DC' --benchmark Public_AR_Census2020 --timeout 30
```

--------------------------------

### Basic Geocoding Functions in Python

Source: https://github.com/fitnr/censusgeocode/blob/master/README.md

Demonstrates the core functionalities of the censusgeocode library for geocoding. It shows how to get coordinates from latitude/longitude, geocode a single address, and process a batch of addresses from a CSV file.

```python
import censusgeocode as cg

cg.coordinates(x=-76, y=41)
cg.onelineaddress('1600 Pennsylvania Avenue, Washington, DC')
cg.address('1600 Pennsylvania Avenue', city='Washington', state='DC', zip='20006')
cg.addressbatch('data/addresses.csv')
```

--------------------------------

### Initialize and Configure CensusGeocode Class

Source: https://context7.com/fitnr/censusgeocode/llms.txt

Shows how to instantiate the CensusGeocode class with custom benchmark and vintage settings, and how to update these configurations dynamically.

```python
from censusgeocode import CensusGeocode

# Initialize with default settings
cg = CensusGeocode()

# Initialize with custom benchmark and vintage
cg = CensusGeocode(benchmark='Public_AR_Census2020', vintage='Census2020_Current')

# Check current benchmark and vintage settings
print(cg.benchmark)  # 'Public_AR_Census2020'
print(cg.vintage)    # 'Census2020_Current'

# Update benchmark and vintage dynamically
cg.set_benchmark('Public_AR_Current')
cg.set_vintage('Current_Current')
```

--------------------------------

### Customizing Benchmark and Vintage

Source: https://github.com/fitnr/censusgeocode/blob/master/README.md

Shows how to instantiate the CensusGeocode class with specific benchmark and vintage settings.

```APIDOC
## Advanced Geocoding Configuration

### Description
Allows for custom configuration of the geocoder by specifying benchmark and vintage.

### Method
N/A (Python Class Instantiation)

### Endpoint
N/A (Python Module)

### Parameters

#### `CensusGeocode(benchmark='Public_AR_Current', vintage='Census2020_Current', **kwargs)`
- **benchmark** (str) - Optional - The benchmark to use for geocoding. Defaults to 'Public_AR_Current'.
- **vintage** (str) - Optional - The vintage to use for geocoding. Defaults to 'Current_Current'.

### Request Example
```python
from censusgeocode import CensusGeocode

# Instantiate with a specific benchmark and vintage
cg = CensusGeocode(benchmark='Public_AR_Current', vintage='Census2020_Current')

# Use the configured instance for geocoding
result = cg.onelineaddress('1600 Pennsylvania Avenue, Washington, DC')
```

### Response
#### Success Response (200)
Similar to basic geocoding, returns a CensusResult object with geocoding information based on the specified benchmark and vintage.

#### Response Example
```json
{
    "input": {
        "vintage": {
            "vintageName": "Census2020_Current",
            "id": "9",
            "vintageDescription": "Census 2020 Vintage - Current Benchmark",
            "isDefault": False
        },
        "benchmark": {
            "benchmarkName": "Public_AR_Current",
            "id": "4",
            "isDefault": False,
            "benchmarkDescription": "Public Address Ranges - Current Benchmark"
        },
        "location": {
            "y": 38.8976757,
            "x": -77.0365297
        }
    },
    "results": [
        {
            "2020 Census Blocks": [
                {
                    "AREALAND": 1409023,
                    "AREAWATER": 0,
                    "BASENAME": "1045",
                    "BLKGRP": "1",
                    "BLOCK": "1045",
                    "CENTLAT": "+38.8976757",
                    "CENTLON": "-077.0365297",
                    "COUNTY": "001",
                    "FUNCSTAT": "A",
                    "GEOID": "110010001001045",
                    "INTPTLAT": "+38.8976757",
                    "INTPTLON": "-077.0365297",
                    "LSADC": "BK",
                    "LWBLKTYP": "L",
                    "MTFCC": "G5040",
                    "NAME": "Block 1045",
                    "OBJECTID": 1234567,
                    "OID": 987654321,
                    "STATE": "11",
                    "SUFFIX": "",
                    "TRACT": "000100"
                }
            ]
        }
    ]
}
```
```

--------------------------------

### Perform Geocoding with Convenience Functions

Source: https://context7.com/fitnr/censusgeocode/llms.txt

Demonstrates the use of module-level convenience functions for quick geocoding tasks including coordinate lookup, single-line address geocoding, structured address input, and batch processing from CSV files.

```python
import censusgeocode as cg

# Geocode by coordinates (longitude, latitude) - returns Census geographies
result = cg.coordinates(x=-76, y=41)
print(result['Counties'][0]['NAME'])  # 'Luzerne County'
print(result['States'][0]['NAME'])    # 'Pennsylvania'

# Geocode a single-line address
result = cg.onelineaddress('1600 Pennsylvania Avenue, Washington, DC')
print(result[0]['coordinates'])  # {'x': -77.03535, 'y': 38.898754}

# Geocode with structured address components
result = cg.address('1600 Pennsylvania Avenue', city='Washington', state='DC', zip='20006')

# Batch geocode from a CSV file
results = cg.addressbatch('addresses.csv')
for row in results:
    print(f"{row['id']}: {row['lat']}, {row['lon']}")
```

--------------------------------

### Advanced Geocoding Configuration in Python

Source: https://github.com/fitnr/censusgeocode/blob/master/README.md

Explains how to use the CensusGeocode class for advanced configurations, allowing the specification of different benchmarks and vintages for geocoding requests. This is useful when specific historical or updated data is required.

```python
from censusgeocode import CensusGeocode
cg = CensusGeocode(benchmark='Public_AR_Current', vintage='Census2020_Current')
cg.onelineaddress(foobar)
```

--------------------------------

### Perform Reverse Geocoding with coordinates()

Source: https://context7.com/fitnr/censusgeocode/llms.txt

Explains how to use the coordinates method to convert longitude and latitude into detailed Census geographic information, including state, county, and tract data.

```python
from censusgeocode import CensusGeocode

cg = CensusGeocode()

# Reverse geocode coordinates (x=longitude, y=latitude)
result = cg.coordinates(x=-74, y=43)

# Access geographic data by layer
print(result['States'][0]['NAME'])        # 'New York'
print(result['States'][0]['STUSAB'])      # 'NY'
print(result['Counties'][0]['NAME'])      # 'Saratoga County'
print(result['Counties'][0]['GEOID'])     # '36091'
print(result['Census Tracts'][0]['TRACT'])  # '061500'
print(result['2010 Census Blocks'][0]['BLOCK'])  # Block number

# Access centroid and internal point coordinates
county = result['Counties'][0]
print(county['CENT'])   # (longitude, latitude) tuple of centroid
print(county['INTPT'])  # (longitude, latitude) tuple of internal point

# Access the input that was sent to the API
print(result.input['location'])  # {'x': -74, 'y': 43}
print(result.input['benchmark']['benchmarkName'])  # 'Public_AR_Current'
```

--------------------------------

### Python: Using CensusGeocode for Address and Coordinate Geocoding

Source: https://context7.com/fitnr/censusgeocode/llms.txt

Demonstrates how to use the CensusGeocode library to geocode addresses and coordinates. It shows how to access results as list-like AddressResult objects and dictionary-like GeographyResult objects, including accessing the input parameters used for the query. The code highlights accessing match details, input benchmark/vintage information, geography layer keys, and coordinate data.

```python
from censusgeocode import CensusGeocode

cg = CensusGeocode()

# AddressResult - returned by address/onelineaddress with returntype='locations'
result = cg.onelineaddress('1600 Pennsylvania Ave, Washington, DC', returntype='locations')

# Access as a list
print(len(result))           # Number of matches
print(result[0])             # First match dict

# Access input information
print(result.input['benchmark']['benchmarkName'])  # 'Public_AR_Current'
print(result.input['vintage']['vintageName'])      # 'Current_Current'

# GeographyResult - returned by coordinates()
result = cg.coordinates(x=-76, y=41)

# Access as a dictionary with geography layer keys
print(result.keys())  # dict_keys(['States', 'Counties', 'Census Tracts', '2010 Census Blocks'])

# Access input information
print(result.input['location'])  # {'x': -76, 'y': 41}

# Each geography has centroid and internal point coordinates
state = result['States'][0]
print(state['CENT'])   # (lon, lat) tuple - centroid
print(state['INTPT'])  # (lon, lat) tuple - internal point
```

--------------------------------

### Perform Single Address Geocoding with Custom Timeout

Source: https://context7.com/fitnr/censusgeocode/llms.txt

Demonstrates how to geocode a single address string using the onelineaddress method while specifying a custom request timeout in seconds.

```python
from censusgeocode import CensusGeocode
cg = CensusGeocode()
result = cg.onelineaddress('Hollywood & Vine, LA, CA', timeout=30)
```

--------------------------------

### Geocode Structured Address Components

Source: https://context7.com/fitnr/censusgeocode/llms.txt

Shows how to geocode addresses using individual components like street, city, state, and zip. Supports different return types and custom benchmark/vintage configurations.

```python
from censusgeocode import CensusGeocode
cg = CensusGeocode()
result = cg.address(street='1600 Pennsylvania Avenue NW', city='Washington', state='DC', zip='20500')
print(result[0]['matchedAddress'])

cg = CensusGeocode(benchmark='Public_AR_Census2020', vintage='Census2020_Current')
result = cg.address(street='1600 Pennsylvania Avenue NW', city='Washington', state='DC', zipcode='20500', returntype='geographies')
```

--------------------------------

### Geocode Single-Line Addresses with onelineaddress()

Source: https://context7.com/fitnr/censusgeocode/llms.txt

Demonstrates geocoding a single string address, including options to return structured location components or detailed geographic data and requesting specific layers.

```python
from censusgeocode import CensusGeocode

cg = CensusGeocode()

# Basic single-line address geocoding (default returntype='geographies')
result = cg.onelineaddress('1600 Pennsylvania Avenue NW, Washington, DC, 20500')

# Access matched address and coordinates
print(result[0]['matchedAddress'])  # '1600 PENNSYLVANIA AVE NW, WASHINGTON, DC, 20502'
print(result[0]['coordinates'])     # {'x': -77.03535, 'y': 38.898754}

# Access geographic data
print(result[0]['geographies']['Counties'][0]['BASENAME'])  # 'District of Columbia'
print(result[0]['geographies']['Census Tracts'][0]['GEOID'])  # '11001006202'

# Get locations only (without geographic data)
result = cg.onelineaddress(
    '1600 Pennsylvania Avenue NW, Washington, DC',
    returntype='locations'
)
print(result[0]['addressComponents']['streetName'])  # 'PENNSYLVANIA'

# Request all available layers
result = cg.onelineaddress(
    '1600 Pennsylvania Avenue NW, Washington, DC, 20500',
    layers='all'
)
print('Metropolitan Divisions' in result[0]['geographies'])  # True
```

--------------------------------

### Basic Geocoding Functions

Source: https://github.com/fitnr/censusgeocode/blob/master/README.md

Demonstrates the basic functions for geocoding addresses using the censusgeocode library.

```APIDOC
## Basic Geocoding

### Description
Provides functions to geocode coordinates, single addresses, and batch addresses.

### Method
N/A (Python Functions)

### Endpoint
N/A (Python Module)

### Parameters

#### `coordinates(x, y, **kwargs)`
- **x** (float) - Required - The longitude coordinate.
- **y** (float) - Required - The latitude coordinate.

#### `onelineaddress(address, **kwargs)`
- **address** (str) - Required - A single line address string.

#### `address(street, city, state, zip, **kwargs)`
- **street** (str) - Required - The street address.
- **city** (str) - Required - The city.
- **state** (str) - Required - The state.
- **zip** (str) - Required - The zip code.

#### `addressbatch(file_path, **kwargs)`
- **file_path** (str) - Required - Path to the CSV file containing addresses.

### Request Example
```python
import censusgeocode as cg

# Geocode by coordinates
result_coords = cg.coordinates(x=-76, y=41)

# Geocode a single line address
result_oneline = cg.onelineaddress('1600 Pennsylvania Avenue, Washington, DC')

# Geocode a structured address
result_address = cg.address('1600 Pennsylvania Avenue', city='Washington', state='DC', zip='20006')

# Geocode a batch of addresses from a CSV file
# result_batch = cg.addressbatch('data/addresses.csv')
```

### Response
#### Success Response (200)
Returns a CensusResult object, which is a list with an additional 'input' property detailing the query interpretation.

#### Response Example
```json
{
    "input": {
        "vintage": {
            "vintageName": "Current_Current",
            "id": "4",
            "vintageDescription": "Current Vintage - Current Benchmark",
            "isDefault": True
        },
        "benchmark": {
            "benchmarkName": "Public_AR_Current",
            "id": "4",
            "isDefault": False,
            "benchmarkDescription": "Public Address Ranges - Current Benchmark"
        },
        "location": {
            "y": 41.0,
            "x": -76.0
        }
    },
    "results": [
        {
            "2010 Census Blocks": [
                {
                    "AREALAND": 1409023,
                    "AREAWATER": 0,
                    "BASENAME": "1045",
                    "BLKGRP": "1",
                    "BLOCK": "1045",
                    "CENTLAT": "+40.9957436",
                    "CENTLON": "-076.0089338",
                    "COUNTY": "079",
                    "FUNCSTAT": "S",
                    "GEOID": "420792166001045",
                    "INTPTLAT": "+40.9957436",
                    "INTPTLON": "-076.0089338",
                    "LSADC": "BK",
                    "LWBLKTYP": "L",
                    "MTFCC": "G5040",
                    "NAME": "Block 1045",
                    "OBJECTID": 9940449,
                    "OID": 210404020212114,
                    "STATE": "42",
                    "SUFFIX": "",
                    "TRACT": "216600"
                }
            ]
        }
    ]
}
```
```

--------------------------------

### POST /addressbatch

Source: https://context7.com/fitnr/censusgeocode/llms.txt

Processes multiple addresses at once from a CSV file or an iterable of dictionaries. Limited to 10,000 records per request.

```APIDOC
## POST /addressbatch

### Description
Processes multiple addresses at once, either from a CSV file or from an iterable of dictionaries. The Census API limits batch requests to 10,000 records.

### Method
POST

### Endpoint
/addressbatch

### Parameters
#### Request Body
- **data** (file/list) - Required - CSV file or list of dictionaries containing address components.
- **returntype** (string) - Optional - 'locations' or 'geographies'.

### Request Example
[
  {"id": 1, "street": "4600 Silver Hill Rd", "city": "Suitland", "state": "MD", "zip": "20746"},
  {"id": 2, "street": "1600 Pennsylvania Ave NW", "city": "Washington", "state": "DC", "zip": "20500"}
]

### Response
#### Success Response (200)
- **results** (array) - A list of geocoding results for each input record.

#### Response Example
[
  {"id": 1, "lat": 38.845, "lon": -76.927, "match": true},
  {"id": 2, "lat": 38.898, "lon": -77.035, "match": true}
]
```

--------------------------------

### Perform Batch Geocoding

Source: https://context7.com/fitnr/censusgeocode/llms.txt

Processes multiple addresses from CSV files, file handles, or lists of dictionaries. The API supports up to 10,000 records per request.

```python
from censusgeocode import CensusGeocode
cg = CensusGeocode()
result = cg.addressbatch('addresses.csv', returntype='locations')

addresses = [{'id': 1, 'street': '4600 Silver Hill Rd', 'city': 'Suitland', 'state': 'MD', 'zip': '20746'}]
result = cg.addressbatch(addresses, returntype='locations')
```

--------------------------------

### Batch Geocode from CSV File with Census Geocoder CLI

Source: https://github.com/fitnr/censusgeocode/blob/master/README.md

Process an entire file of addresses using the censusgeocode tool's batch functionality. The input file must be CSV formatted without a header, containing 'unique id, street address, state, city, zip code' columns. The output is a CSV with geocoding results.

```bash
censusgeocode --csv tests/fixtures/batch.csv
```

--------------------------------

### Batch Geocode from Stdin with Census Geocoder CLI

Source: https://github.com/fitnr/censusgeocode/blob/master/README.md

Geocode addresses from standard input (stdin) by specifying '-' as the filename with the --csv option. This is useful for piping data from other command-line utilities. The batch geocoder is limited to 10,000 rows.

```bash
head tests/fixtures/batch.csv | censusgeocode --csv -
```

--------------------------------

### Add Line Numbers for Batch Geocoding with Unix nl

Source: https://github.com/fitnr/censusgeocode/blob/master/README.md

When input data lacks a unique ID, prepend line numbers using the Unix 'nl' command before piping to censusgeocode. This ensures each record can be uniquely identified in the output. The output is redirected to 'output.csv'.

```bash
nl -s , input.csv | censusgeocode --csv - > output.csv
```

--------------------------------

### POST /address

Source: https://context7.com/fitnr/censusgeocode/llms.txt

Geocodes an address using separate components (street, city, state, zip) for more precise matching.

```APIDOC
## POST /address

### Description
Geocodes an address using separate components (street, city, state, zip). This provides more precise matching when address components are already parsed.

### Method
POST

### Endpoint
/address

### Parameters
#### Request Body
- **street** (string) - Required - The street address.
- **city** (string) - Required - The city name.
- **state** (string) - Required - The state abbreviation.
- **zip** (string) - Optional - The zip code.
- **zipcode** (string) - Optional - Alternative to zip.
- **returntype** (string) - Optional - 'locations' or 'geographies'.

### Request Example
{
  "street": "1600 Pennsylvania Avenue NW",
  "city": "Washington",
  "state": "DC",
  "zip": "20500"
}

### Response
#### Success Response (200)
- **matchedAddress** (string) - The standardized address returned by the API.
- **geographies** (object) - Geographic data if requested.

#### Response Example
{
  "matchedAddress": "1600 PENNSYLVANIA AVE NW, WASHINGTON, DC, 20500",
  "geographies": { ... }
}
```

--------------------------------

### Specifying Return Type in Python

Source: https://github.com/fitnr/censusgeocode/blob/master/README.md

Illustrates how to control the type of information returned by the geocoder. The 'returntype' parameter can be set to 'locations' for address details or 'geographies' for Census geography information (default).

```python
cg.onelineaddress('1600 Pennsylvania Avenue, Washington, DC', returntype='locations')
```

--------------------------------

### Geocode Single Address with Census Geocoder CLI

Source: https://github.com/fitnr/censusgeocode/blob/master/README.md

Use the censusgeocode command to geocode a single address. It takes the address as a string argument and returns a comma-delimited longitude, latitude pair. The tool is capable of recognizing non-standard addresses.

```bash
censusgeocode '100 Fifth Avenue, New York, NY'
-73.992195,40.73797

censusgeocode '1600 Pennsylvania Avenue, Washington DC'
-77.03535,38.898754

censusgeocode 'Hollywood & Vine, LA, CA'
-118.32668,34.101624
```

--------------------------------

### Accessing Geocoding Results in Python

Source: https://github.com/fitnr/censusgeocode/blob/master/README.md

Shows how to interpret the results returned by the censusgeocode library. The 'CensusResult' object, a list subclass, contains geocoded data and an 'input' property detailing how the request was processed by the Census API.

```python
result = cg.coordinates(x=-76, y=41)
print(result.input)
print(result)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.