Skip to content

Secondary address line support #38

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sixlive wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Secondary address line support #38

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9c01857
Secondary address line support
sixlive Jan 12, 2026
00b6b7c
update changelog
sixlive Jan 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 27 additions & 3 deletions source.html.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -670,6 +670,7 @@ ENTERPRISE-->
},
"accuracy": 1,
"accuracy_type": "rooftop",
"sub_accuracy_type": "unit",
"source": "Arlington"
}
]
Expand All @@ -684,6 +685,14 @@ E.g. if the unit number is inputted as `#R500`, the outputted value will be `Ste

In order to verify that the unit number is valid per USPS, you can request the [`zip4`](#usps-zip-4) field append and check the `exact_match` value. If it is set to `true`, it means that the unit number is recognized by USPS.

#### Unit-level coordinates

When unit-level data is available, Geocodio will return coordinates specific to that unit rather than the building centroid. This is indicated by a `sub_accuracy_type` of `"unit"` in the response.

Not all addresses have unit-level coordinate data. When unit data is not available, the `sub_accuracy_type` will be `null` and the coordinates will represent the building's rooftop location.

For reverse geocoding, if the input coordinates are within 50 meters of a known unit location, the response will include the unit information (`secondaryunit` and `secondarynumber`) and set `sub_accuracy_type` to `"unit"`.

### The `input` Object

The `input` object that is returned in the API response is not a one-for-one parsing of the initial address that is provided. In order to ensure that the `address_components` returned in `input` are accurate, we cross-reference them with the `address_components` returned in the `results` object.
Expand Down Expand Up @@ -4168,8 +4177,8 @@ prefix | Abbreviated street prefix, particularly common in the case
street | Name of the street without number, prefix or suffix, e.g. "Main"
suffix | Abbreviated street suffix, e.g. St., Ave. Rd.
postdirectional | Directional that comes after the street name, 1-2 characters, e.g. N or NE
secondaryunit | Name of the secondary unit, e.g. "Apt" or "Unit". For "input" address components only
secondarynumber | Secondary unit number. For "input" address components only
secondaryunit | Name of the secondary unit, e.g. "Apt" or "Unit"
secondarynumber | Secondary unit number
city |
county |
state |
Expand Down Expand Up @@ -4214,6 +4223,17 @@ rooftop | We found the exact point with rooftop level accuracy
nearest_street | Nearest match for a specific street with estimated street number
nearest_place | Closest city/town/place

### Sub-accuracy type

In addition to the main accuracy type, results may include a `sub_accuracy_type` field that indicates enhanced precision within the primary accuracy level.

Value | Description
------ | -----------
unit | The coordinates represent a specific unit (apartment, suite, etc.) within a building rather than the building centroid
null | No sub-accuracy enhancement (default)

The `sub_accuracy_type` field is only populated for results with `accuracy_type` of `rooftop`. When unit-level data is available and the geocoded address includes a secondary address line (unit, apartment, suite number), the returned coordinates will be specific to that unit.

# Address formats
Geocodio supports geocoding the following address components:

Expand All @@ -4224,7 +4244,7 @@ Geocodio supports geocoding the following address components:
* Counties
* States
* PO Boxes (coordinates will be returned as a centroid of the zip code)
* Second address lines such as unit and apartment numbers (not used for determining the exact coordinates at this time)
* Second address lines such as unit and apartment numbers (used to determine unit-level coordinates when available, see [Geocoding with Unit Numbers](#geocoding-with-unit-numbers))

If a city is provided without a state, Geocodio will automatically guess and add the state based on what it is most likely to be. Geocodio also understands shorthands for both streets and cities, for example *NYC*, *SF*, etc., are acceptable city names.

Expand Down Expand Up @@ -4597,6 +4617,10 @@ Breaking changes are defined as changes that remove or rename properties in the

## v1.9

*Released on January 16, 2026*

* Secondary address lines (unit, apartment, suite numbers) are now used to determine [unit-level coordinates](#geocoding-with-unit-numbers) when available. A new `sub_accuracy_type` field with value `"unit"` indicates when unit-level precision is returned. This works for both forward and reverse geocoding.

*Released on January 6, 2026*

* Added new [Distance](#distance) endpoints for calculating distances and travel times between locations
Expand Down
46 changes: 31 additions & 15 deletions source/enterprise/index.html.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,12 +21,14 @@ code_clipboard: true

# Introduction

Geocodio's RESTful API allows you to perform forward and reverse geocoding lookups as well as simultaneously enrich your address data. Geocodio's API supports individual, batch, and list geocoding.
Geocodio's RESTful [geocoding API](#geocoding) endpoints allows you to perform forward and reverse geocoding lookups for the US and Canada as well as simultaneously enrich your address data. Geocodio's geocoding API supports individual, batch, and list (CSV) geocoding.

Data appends (`fields`) include Census geographies and data, electoral districts, timezones, school districts, and more.

The base API url is `https://api.enterprise.geocod.io/v1.9/`.

Geocodio's [distance API](#distance) endpoints allow you to calculate driving time, driving distance, and straight line (as the crow flies/haversine) distance between addresses or coordinates. One-to-one, one-to-many, and many-to-many matrices are supported, and you can limit results to a specified radius.

All HTTP responses (including errors) are returned with [JSON-formatted](http://www.json.org) output.

We may add additional properties to the output in the future, but existing properties will never be changed or removed without a new API version release.
Expand Down Expand Up @@ -339,7 +341,7 @@ You must specifically enable permissions for the [lists API](#geocoding-lists) a

# Overview

Geocodio's geocoding API supports three different methods for processing your data. Geocodio is designed to make high-volume geocoding and data enrichment easier, yet we also support real-time single requests.
Geocodio's **geocoding API** supports three different methods for processing your data. Geocodio is designed to make high-volume geocoding and data enrichment easier, yet we also support real-time single requests.

Single and batch geocoding methods are synchronous, meaning that you have to wait for the data to be fully processed and will receive it directly in your API response. The [list geocoding](#geocoding-lists) method is asynchronous and requires a second request to be made to download the data once it is ready.

Expand All @@ -352,7 +354,7 @@ Name | Batch size | Type | Form
[Batch geocoding](#batch-geocoding) | Up to 10,000 | Synchronous | JSON | <i class="fa fa-check"></i> | <i class="fa fa-check"></i>
[List geocoding](#geocoding-lists) | Up to 10,000,000+ | Asynchronous | CSV/TSV/Excel | <i class="fa fa-check"></i> | <i class="fa fa-check"></i>

Geocodio's distance APIs allow you to calculate driving time, driving distance, and straight line (as the crow flies/haversine) distance between addresses or coordinates. One-to-one, one-to-many, and many-to-many matrices are supported, and you can limit results to a specified radius.
Geocodio's **distance API** endpoints allow you to calculate driving time, driving distance, and straight line (as the crow flies/haversine) distance between addresses or coordinates. One-to-one, one-to-many, and many-to-many matrices are supported, and you can limit results to a specified radius.

Like the geocoding API, the method you choose depends on your use case.

Expand All @@ -364,8 +366,6 @@ Name | Batch size (calculations) | Type
[Distance matrix](#distance-matrix) | Up to 10,000 | Synchronous | JSON | <i class="fa fa-check"></i> |
[Distance jobs](#distance-jobs-async) | Up to 50,000 | Asynchronous | JSON | <i class="fa fa-check"></i> |

If in doubt, [single geocoding](#geocoding) is the simplest choice for many use cases.

# Geocoding

Geocoding (also known as forward geocoding) allows you to convert one or more addresses into geographic coordinates (i.e. latitude and longitude). Geocoding will also parse the address and append additional information (e.g. if you specify a ZIP code, Geocodio will return the city and state corresponding to the zip code as well)
Expand Down Expand Up @@ -670,6 +670,7 @@ Accuracy breakdown descriptions and scores are subject to change and should not
},
"accuracy": 1,
"accuracy_type": "rooftop",
"sub_accuracy_type": "unit",
"source": "Arlington"
}
]
Expand All @@ -684,6 +685,14 @@ E.g. if the unit number is inputted as `#R500`, the outputted value will be `Ste

In order to verify that the unit number is valid per USPS, you can request the [`zip4`](#usps-zip-4) field append and check the `exact_match` value. If it is set to `true`, it means that the unit number is recognized by USPS.

#### Unit-level coordinates

When unit-level data is available, Geocodio will return coordinates specific to that unit rather than the building centroid. This is indicated by a `sub_accuracy_type` of `"unit"` in the response.

Not all addresses have unit-level coordinate data. When unit data is not available, the `sub_accuracy_type` will be `null` and the coordinates will represent the building's rooftop location.

For reverse geocoding, if the input coordinates are within 50 meters of a known unit location, the response will include the unit information (`secondaryunit` and `secondarynumber`) and set `sub_accuracy_type` to `"unit"`.

### The `input` Object

The `input` object that is returned in the API response is not a one-for-one parsing of the initial address that is provided. In order to ensure that the `address_components` returned in `input` are accurate, we cross-reference them with the `address_components` returned in the `results` object.
Expand Down Expand Up @@ -850,9 +859,7 @@ geocoder.geocode('1109 N Highland St, Arlington VA', [], null, {

When `destinations[]` is provided, each geocoded result will include a `destinations` array containing the distance and duration (if using `driving` mode) to each destination location. This is useful for finding the nearest locations to a geocoded address.

<aside class="notice">
See the <a href="#distance">Distance</a> section for more details on distance calculation options and dedicated distance endpoints. To use Geocodio's Distance endpoints, you'll need to enable access on an API key level [via the dashboard](https://dash.enterprise.geocod.io/apikey).
</aside>
See the <a href="#distance">Distance</a> section for more details on distance calculation options and dedicated distance endpoints. To use Geocodio's Distance endpoints, you'll need to enable access on an API key level <a href="https://dash.enterprise.geocod.io/apikey">via the dashboard</a>.

## Batch geocoding

Expand Down Expand Up @@ -7902,9 +7909,7 @@ Name | Batch size (calculations) | Type
[Distance matrix](#distance-matrix) | Up to 10,000 | Synchronous | JSON | <i class="fa fa-check"></i> |
[Distance jobs](#distance-jobs-async) | Up to 50,000 | Asynchronous | JSON | <i class="fa fa-check"></i> |

<aside class="notice">
To use Geocodio's Distance endpoints, you'll need to enable access on an API key level [via the dashboard](https://dash.enterprise.geocod.io/apikey).
</aside>
To use Geocodio's Distance API endpoints, you'll need to enable access on an API key level <a href="https://dash.enterprise.geocod.io/apikey">via the dashboard</a>.

## Location formats

Expand Down Expand Up @@ -8926,8 +8931,8 @@ prefix | Abbreviated street prefix, particularly common in the case
street | Name of the street without number, prefix or suffix, e.g. "Main"
suffix | Abbreviated street suffix, e.g. St., Ave. Rd.
postdirectional | Directional that comes after the street name, 1-2 characters, e.g. N or NE
secondaryunit | Name of the secondary unit, e.g. "Apt" or "Unit". For "input" address components only
secondarynumber | Secondary unit number. For "input" address components only
secondaryunit | Name of the secondary unit, e.g. "Apt" or "Unit"
secondarynumber | Secondary unit number
city |
county |
state |
Expand Down Expand Up @@ -8972,6 +8977,17 @@ rooftop | We found the exact point with rooftop level accuracy
nearest_street | Nearest match for a specific street with estimated street number
nearest_place | Closest city/town/place

### Sub-accuracy type

In addition to the main accuracy type, results may include a `sub_accuracy_type` field that indicates enhanced precision within the primary accuracy level.

Value | Description
------ | -----------
unit | The coordinates represent a specific unit (apartment, suite, etc.) within a building rather than the building centroid
null | No sub-accuracy enhancement (default)

The `sub_accuracy_type` field is only populated for results with `accuracy_type` of `rooftop`. When unit-level data is available and the geocoded address includes a secondary address line (unit, apartment, suite number), the returned coordinates will be specific to that unit.

# Address formats
Geocodio supports geocoding the following address components:

Expand All @@ -8982,7 +8998,7 @@ Geocodio supports geocoding the following address components:
* Counties
* States
* PO Boxes (coordinates will be returned as a centroid of the zip code)
* Second address lines such as unit and apartment numbers (not used for determining the exact coordinates at this time)
* Second address lines such as unit and apartment numbers (used to determine unit-level coordinates when available, see [Geocoding with Unit Numbers](#geocoding-with-unit-numbers))

If a city is provided without a state, Geocodio will automatically guess and add the state based on what it is most likely to be. Geocodio also understands shorthands for both streets and cities, for example *NYC*, *SF*, etc., are acceptable city names.

Expand Down Expand Up @@ -9321,7 +9337,7 @@ The `components` parameter supports filtering results:

**Coverage:**

* ⚠️ **US and Canada only** - Geocodio currently supports US and Canadian addresses. Requests for other countries will return `ZERO_RESULTS` status
* ⚠️ **US and Canada only** - Geocodio currently supports US and Canadian addresses, and reverse geocoding in US, Canada, and Mexico. Requests for other countries will return `ZERO_RESULTS` status

**Error Responses:**

Expand Down
Loading