Name: US Address Geocoder – Address to Lat/Lon | Free · $9/mo | API.market
Brand: airelit
SKU: api-airelit-geocode
Availability: InStock
Author: API Market

### 🗺️ US Address Geocoder

A practical geocoder built for developers — converts US street addresses to latitude/longitude coordinates. Single or Bulk geocoding. 

---

### How It Works

Built on **OpenAddresses** (primary) with **TIGER** interpolation as a fallback.

**Two-stage matching pipeline:**

| Stage | Method | Description |
|-------|--------|-------------|
| 1 | OpenAddresses | Point-level rooftop matching (high accuracy) |
| 2 | TIGER Interpolation | Street segment estimation for missing addresses |

Every response includes a `rating` and `source` so you know exactly how the result was generated.

---

### Coverage

- 🇺🇸 United States (50 States + Washington D.C. + 🌴 Puerto Rico)

---

### What Makes This Different

#### ✅ Results Are Yours to Keep
Most commercial geocoders **prohibit storing coordinates** and require re-querying their service. This API is built on open/public datasets — meaning:

- Results **may be cached**
- Results **may be stored permanently**
- No re-query requirements
- No vendor lock-in

&gt; Geocode once and keep the coordinates.

---

#### 📦 Simple Batch Processing

Process up to **100 addresses per request** via the batch endpoint — ideal for:

- CRM enrichment
- Nightly ETL jobs
- Property dataset processing
- Bulk analytics pipelines

&gt; Each address processed counts as **one request credit**.

---

#### 📊 Transparent Confidence Scoring

Every response includes a `rating` value:

| Rating | Meaning |
|--------|---------|
| `0` | Exact point match |
| `1–10` | Strong match |
| `11–20` | Weaker interpolation |

Applications can define their own acceptance threshold.

---

#### 🔄 Updated Monthly

The geocoder database is refreshed monthly from:
- OpenAddresses
- US Census TIGER

---

### Example Response

```json
{
  "lat": 41.1223607,
  "lon": -112.0335751,
  "rating": 1,
  "source": "openaddress",
  "resolved_address": "623 N Ann St, Clearfield, UT 84015"
}
```

| Field | Description |
|-------|-------------|
| `lat` / `lon` | WGS84 coordinates |
| `rating` | Confidence score (lower = better) |
| `source` | `openaddress` or `tiger` |
| `resolved_address` | Canonical address from the geocoder |

---

### Good Use Cases

- CRM and lead enrichment
- Property datasets
- Logistics preprocessing
- Analytics pipelines
- Bulk geocoding workflows

---

### ⚠️ Limitations

- US addresses only
- Rural addresses may resolve via street interpolation
- P.O. boxes and rural route addresses typically **cannot** be geocoded

---

### ⚡ Performance

| Request Type | Expected Latency |
|--------------|-----------------|
| Single address | ~10–20 ms |
| Clean batch | Hundreds of ms |
| Interpolation-heavy batch | Several seconds |

&gt; Batch requests should be configured with **longer timeouts**.

# US Address Geocoder API — Developer Reference

## Overview

Supports single lookups and batch processing of up to 100 addresses per request.

Results include a **confidence rating**, the **data source**, and the **resolved canonical address** as stored in the geocoder database — **not**  an echo of your input.

---

## Base URL

```
https://prod.api.market/api/v1/airelit/geocode
```

---

## Authentication

All requests require your api.market credentials in the headers:

```
x-api-market-key: YOUR_KEY" 
Content-Type: application/json
```

---

## Endpoints

### POST `/single`

Geocode a single US address.

#### Request Body

| Field     | Type   | Required | Description                              |
|-----------|--------|----------|------------------------------------------|
| `address` | string | Yes      | Full US street address. Must include a street number, street name, and either a state abbreviation or ZIP code. Max 150 characters. |

#### Example Request

```json
{
  "address": "339 Bernardo Ave Suite 200, Mountain View, CA 94043"
}
```

```bash
curl -X POST "https://prod.api.market/api/v1/airelit/geocode/single" \
  -H "x-api-market-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address": "339 Bernardo Ave Suite 200, Mountain View, CA 94043"}'
```

#### Success Response — `200 OK`

```json
 {
    "lat": 37.3878636,
    "lon": -122.0506232,
    "rating": 1,
    "source": "openaddress",
    "resolved_address": "339 N Bernardo Ave, Mountain View,  94043"
  }
```

#### Response Fields

| Field              | Type           | Description                                                                                  |
|--------------------|----------------|----------------------------------------------------------------------------------------------|
| `lat`              | float          | WGS84 latitude                                                                               |
| `lon`              | float          | WGS84 longitude                                                                              |
| `rating`           | integer        | Confidence score. **0 = exact match.** Lower is better. Results above 20 are rejected.      |
| `source`           | string         | `openaddress` (point-level match) or `tiger` (interpolated)                                  |
| `resolved_address` | string or null | Canonical address as recorded in the geocoder database. May differ from your input.         |

---

### POST `/batch`

Geocode up to **100 addresses** in a single request. Each address is processed against the same database connection, minimizing latency overhead versus making 100 individual calls.

Each item in the request carries a client-supplied `id`. Results are returned in the same order as the request, with the `id` preserved — including items that failed validation or could not be geocoded.

#### Billing Note

Each address in a batch counts as one API call toward your plan quota.

#### Request Body

| Field       | Type  | Required | Description                                          |
|-------------|-------|----------|------------------------------------------------------|
| `addresses` | array | Yes      | Array of address objects. Maximum 100 per request.  |

Each address object:

| Field     | Type   | Required | Description                         |
|-----------|--------|----------|-------------------------------------|
| `id`      | string | Yes      | Your identifier. Returned as-is.   |
| `address` | string | Yes      | Full US street address.             |

#### Example Request

```json
{
  "addresses": [
    { "id": "req-001", "address": "339 Bernardo Ave Suite 200, Mountain View, CA 94043" },
    { "id": "req-002", "address": "10700 Escondido Canyon Rd, Agua Dulce, CA 91390" },
    { "id": "req-003", "address": "bad input" }
  ]
}
```

```bash
curl -X POST "https://prod.api.market/api/v1/airelit/geocode/batch" \
  -H "x-api-market-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d @addresses.json
```

#### Success Response — `200 OK`

```json
{
    "results": [
        {
        "id": "req-001",
        "lat": 37.3878636,
        "lon": -122.0506232,
        "rating": 1,
        "source": "openaddress",
        "resolved_address": "339 N Bernardo Ave, Mountain View,  94043"
        },
        {
        "id": "req-002",
        "lat": 34.4893592609069,
        "lon": -118.3203127918381,
        "rating": 10,
        "source": "tiger",
        "resolved_address": "10700 Escondido Canyon Rd, Agua Dulce, CA 91390"
        },
        {
        "id": "req-003",
        "error": "Address is too short."
        }
    ]
}
```

**Failed items do not abort the batch.** Each result carries either the geocode data or an `error` string — your `id` is always present so you can reconcile results against your input.

---

## Error Responses

### Item-Level Errors (batch only)

These appear inline within the `results` array and do not affect other items:

| Error message                                                      | Cause                                             |
|--------------------------------------------------------------------|---------------------------------------------------|
| `Address is too short.`                                            | Fewer than 8 characters after normalisation       |
| `Address is too long.`                                             | Exceeds 150 characters                            |
| `Address must contain at least one number.`                        | No street number found                            |
| `Address must end with a valid US state abbreviation or ZIP code.` | Last token is not a 2-letter state or 5-digit ZIP |
| `Address appears incomplete.`                                      | Address ends with a comma                         |
| `Unable to geocode address with sufficient confidence.`            | Geocoder returned no match above the rating threshold |

### Request-Level Errors

These abort the entire request and return a top-level error object:

| HTTP | Code                  | Cause                                                    |
|------|-----------------------|----------------------------------------------------------|
| 400  | `INVALID_JSON`        | Body is not valid JSON                                   |
| 400  | `INVALID_PARAMS`      | Missing required field, or batch exceeds 100 items       |
| 400  | `INVALID_INPUT`       | Single endpoint: address failed pre-validation           |
| 400  | `NOT_FOUND`           | Single endpoint: geocoder produced no confident result   |
| 503  | `SERVICE_UNAVAILABLE` | Geocoder database unreachable (transient — retry after 2s) |

```json
{
  "error": true,
  "code": "INVALID_PARAMS",
  "message": "Request body must include a non-empty \"addresses\" array."
}
```

---

## Coverage

- **Country:** United States only (contiguous US, Alaska, Hawaii, Puerto Rico)
- **Data sources:** TIGER/Line (US Census Bureau) + OpenAddresses
- **Update cadence:** Monthly
- **Address types:** Street-level addresses. P.O. boxes, rural routes, and intersections are not supported.

---

## Confidence Rating Guide

The `rating` field comes directly from the geocoder. Use it to decide whether to trust a result:

| Rating  | Meaning                                         | Recommendation        |
|---------|-------------------------------------------------|-----------------------|
| 0       | Exact point match (OpenAddresses)               | Trust fully           |
| 1–5     | Very high confidence interpolation              | Trust                 |
| 6–10    | High confidence                                 | Trust for most uses   |
| 11–20   | Moderate confidence                             | Verify if precision matters |
| &gt; 20    | Low confidence — **rejected, not returned**     | —                     |

---

## Caching

You are free to cache and store geocode results. Results are yours once returned — there are no restrictions on storing coordinates for your own use cases. Given the monthly update cadence, a cache TTL of **30 days** is a reasonable default for most applications. For high-churn address lists (logistics, real estate), you may want to re-geocode monthly to catch corrections.

---

## Rate Limits

Rate limits are enforced per plan. Batch requests count one call per address, not one call per request. If you exceed your plan limit, requests return HTTP `429`. Upgrade your plan or contact us for a custom quota.

---

## Tips for Best Results

- Always include a **ZIP code or state abbreviation** at the end of the address. This is the single biggest factor in geocoding accuracy.
- Avoid extraneous text like `"Apt"` or `"Suite"` without a number — `"Apt 4B"` is fine, `"Apt"` alone can confuse the parser.
- For batch jobs, send the maximum 100 addresses per request rather than making individual calls — the latency per address drops significantly.
- If `resolved_address` differs substantially from your input, consider using the resolved form going forward to improve future match rates.
- Addresses with `source: openaddress` and `rating: 0` are point-level matches from the OpenAddresses dataset and are the most precise results available.

Convert any US address to precise lat/lon coordinates. Store & cache results forever. Free 500 calls/mo, from $9/mo. Start free on API.market.

US Address Geocoder – Address to Lat/Lon | Free · $9/mo | API.market

Free