cartodb4/dataservices-api
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #553 from CartoDB/531-document-batch-geocoding

Browse Source 
TomTom as default LDS provider and reference documentation for cdb_bulk_geocode_street_point
This commit is contained in:
Javier Torres 2019-03-25 13:31:12 +01:00 committed by GitHub
commit f1bfc70e6e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 46 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/developer-center/guides/01-overview.md
View File

@ -4,7 +4,7 @@ By using CARTO libraries and the SQL API, you can apply location data services t
**Note:** Based on your account plan, some of these data services are subject to different [quota limitations]({{site.dataservicesapi_docs}}/support/quota-information/).
_In order to supply the best location data services from within our CARTO Engine, the Data Services API collaborates with [Mapbox](https://www.mapbox.com/) and several other geospatial service providers. [Contact us](mailto:sales@carto.com) if you have any specific questions or requirements about the location data service provider being used with your account._
_In order to supply the best location data services from within our CARTO Engine, the Data Services API collaborates with [TomTom](https://www.tomtom.com/) and several other geospatial service providers. [Contact us](mailto:sales@carto.com) if you have any specific questions or requirements about the location data service provider being used with your account._
### Data Services Integration

44
docs/developer-center/reference/05-geocoding-functions.md
View File

@ -311,7 +311,7 @@ INSERT INTO {tablename} (the_geom) SELECT cdb_geocode_ipaddress_point('102.23.34
### Street-Level Geocoder
This function geocodes your data into a point geometry for a street address. CARTO platform uses [Mapbox geocoding services](https://www.mapbox.com/) by default as the service provider for street-level geocoding. [Contact us](mailto:sales@carto.com) if you have any specific questions or requirements about the location data service provider being used with your account.
These functions geocode your data into a point geometry for a street address. CARTO platform uses [TomTom geocoding services](https://www.tomtom.com/) by default as the service provider for street-level geocoding. [Contact us](mailto:sales@carto.com) if you have any specific questions or requirements about the location data service provider being used with your account.
**This service is subject to quota limitations, and extra fees may apply**. View the [Quota information]({{site.dataservicesapi_docs}}/support/quota-information/) for details and recommendations about quota consumption.
@ -345,3 +345,45 @@ UPDATE {tablename} SET the_geom = cdb_geocode_street_point({street_name_column})
```bash
INSERT INTO {tablename} (the_geom) SELECT cdb_geocode_street_point('651 Lombard Street', 'San Francisco', 'California', 'United States')
```
#### cdb_bulk_geocode_street_point (_query text, street_column text, [city_column text], [state_column text], [country_column text], [batch_size integer]_)
Geocodes complete street addresses into point data. Similar to `cdb_geocode_street_point`, but using batch services and therefore allowing for several addresses to be geocoded in a single API call.
##### Arguments
Name | Type | Description
--- | --- | --- | ---
`query` | `text` | SQL query that returns the addresses to be geocoded. It must include a `cartodb_id` column and another column to get the free-form addresses from. Optionally, it may include other columns to fine-tune the geocoding, such as a city column, a state column and a country column.
`street_column` | `text` | Name of the free-form address column, must be present in the SQL query.
`city_column` | `text` | (Optional) Name of the city column, if present in the SQL query.
`state_column` | `text` | (Optional) Name of the state column, if present in the SQL query.
`country_column` | `text` | (Optional) Name of the country column, if present in the SQL query.
`batch_size` | `integer` | (Optional) Geocoding queries are sent in batches. Batch size can be configured, from 1 geocoding query per batch to a maximum value, limited by user quota or other limits. If not specified, it defaults to the maximum size available to the user, which is typically the best option, performance-wise.
##### Returns
Geocoding results are returned in an array. Each array element contains:
Name | Type | Description
--- | --- | --- | ---
`cartodb_id` | `integer` | `cartodb_id` from the original query.
`the_geom` | `Geometry (point, EPSG 4326)` | Point that corresponds to the most accurate match found for this particular address, or `null` if no match was found.
`metadata` | `JSON` | Information about the geocoding result, empty if no match was found.
The `metadata` JSON type includes the following attributes when geocoding was successful:
Name | Type | Description
--- | --- | --- | ---
`precision` | `text` | One of `precise` or `interpolated`.
`relevance` | `number` | Relevance factor, from 0 to 1, higher being more relevant.
`match_type` | `text` | Array with one of `point_of_interest`, `country`, `state`, `county`, `locality`, `district`, `street`, `intersection`, `street_number`, `postal_code`. Empty array if match type is unknown.
##### Example
###### Update the geometries of an entire table by geocoding all the rows based on a street address
```bash
WITH geocoding_results AS (SELECT cartodb_id, the_geom FROM cdb_bulk_geocode_street_point('SELECT cartodb_id, {address_column} from {tablename}', '{address_column}')) UPDATE {tablename} tn SET the_geom = geocoding_results.the_geom FROM geocoding_results WHERE tn.cartodb_id = geocoding_results.cartodb_id
```