diff --git a/source.html.md b/source.html.md index c8842ffaa20..87a0d4be8d4 100644 --- a/source.html.md +++ b/source.html.md @@ -670,6 +670,7 @@ ENTERPRISE--> }, "accuracy": 1, "accuracy_type": "rooftop", + "sub_accuracy_type": "unit", "source": "Arlington" } ] @@ -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. @@ -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 | @@ -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: @@ -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. @@ -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 diff --git a/source/enterprise/index.html.md b/source/enterprise/index.html.md index 9b4dea0bbd8..b34619d0baf 100644 --- a/source/enterprise/index.html.md +++ b/source/enterprise/index.html.md @@ -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. @@ -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. @@ -352,7 +354,7 @@ Name | Batch size | Type | Form [Batch geocoding](#batch-geocoding) | Up to 10,000 | Synchronous | JSON | | [List geocoding](#geocoding-lists) | Up to 10,000,000+ | Asynchronous | CSV/TSV/Excel | | -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. @@ -364,8 +366,6 @@ Name | Batch size (calculations) | Type [Distance matrix](#distance-matrix) | Up to 10,000 | Synchronous | JSON | | [Distance jobs](#distance-jobs-async) | Up to 50,000 | Asynchronous | JSON | | -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) @@ -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" } ] @@ -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. @@ -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. - +See the Distance 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. ## Batch geocoding @@ -7902,9 +7909,7 @@ Name | Batch size (calculations) | Type [Distance matrix](#distance-matrix) | Up to 10,000 | Synchronous | JSON | | [Distance jobs](#distance-jobs-async) | Up to 50,000 | Asynchronous | JSON | | - +To use Geocodio's Distance API endpoints, you'll need to enable access on an API key level via the dashboard. ## Location formats @@ -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 | @@ -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: @@ -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. @@ -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:** diff --git a/source/index.html.md b/source/index.html.md index 1acb9e96950..9920720b319 100644 --- a/source/index.html.md +++ b/source/index.html.md @@ -25,10 +25,10 @@ Geocodio's RESTful [geocoding API](#geocoding) endpoints allows you to perform f Data appends (`fields`) include Census geographies and data, electoral districts, timezones, school districts, and more. -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. - The base API url is `https://api.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. @@ -670,6 +670,7 @@ ENTERPRISE--> }, "accuracy": 1, "accuracy_type": "rooftop", + "sub_accuracy_type": "unit", "source": "Arlington" } ] @@ -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. @@ -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. - ## Batch geocoding @@ -7902,9 +7909,7 @@ Name | Batch size (calculations) | Type [Distance matrix](#distance-matrix) | Up to 10,000 | Synchronous | JSON | | [Distance jobs](#distance-jobs-async) | Up to 50,000 | Asynchronous | JSON | | - ## Location formats @@ -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 | @@ -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: @@ -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. @@ -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:**