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

Remove selects from geocoding functions

Browse Source
This commit is contained in:
Carla Iriberri 2016-05-04 20:00:04 +02:00
parent 5ea0d0e6da
commit fdc58f1eb0
1 changed files with 68 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

125
doc/geocoding_functions.md
View File

@ -16,6 +16,13 @@ In order to geocode an existent CartoDB dataset, an SQL UPDATE statement must be
https://{username}.cartodb.com/api/v2/sql?q=UPDATE {tablename} SET the_geom = cdb_geocode_admin0_
```
Notice that you can make use of Postgres or PostGIS functions in your Data Services API requests, as the result is a geometry that can be handled by the system. For example, suppose you need to retrieve the centroid of a specific country, you can wrap the resulting geometry from the geocoder functions inside the PostGIS `ST_Centroid` function:
```bash
https://{username}.cartodb.com/api/v2/sql?q=UPDATE {tablename} SET the_geom = ST_Centroid(cdb_geocode_admin0_polygon('USA'))&api_key={api_key}
```
The following geocoding functions are available, grouped by categories.
## Country Geocoder
@ -38,18 +45,17 @@ Geometry (polygon, EPSG 4326) or null
#### Example
##### Select
```bash
SELECT cdb_geocode_admin0_polygon('France')
```
##### Update
##### Update the geometry of a table to geocode it
```bash
UPDATE {tablename} SET the_geom = cdb_geocode_admin0_polygon({country_column})
```
##### Insert a geocoded row into a table
```bash
UPDATE {tablename} SET the_geom = cdb_geocode_admin0_polygon('France')
```
## Level-1 Administrative Regions Geocoder
@ -71,18 +77,19 @@ Geometry (polygon, EPSG 4326) or null
#### Example
##### Select
```bash
SELECT cdb_geocode_admin1_polygon('Alicante')
```
##### Update
##### Update the geometry of a table to geocode it
```bash
UPDATE {tablename} SET the_geom = cdb_geocode_admin1_polygon({province_column})
```
##### Insert a geocoded row into a table
```bash
UPDATE {tablename} SET the_geom = cdb_geocode_admin1_polygon('Alicante')
```
### cdb_geocode_admin1_polygon(_admin1_name text, country_name text_)
Geocodes the name of the province/state for a specified country into a Level-1 administrative region, displayed as a polygon geometry.
@ -100,17 +107,16 @@ Geometry (polygon, EPSG 4326) or null
#### Example
##### Select
```bash
SELECT cdb_geocode_admin1_polygon('Alicante', 'Spain')
```
##### Update
##### Update the geometry of a table to geocode it
```bash
UPDATE {tablename} SET the_geom = cdb_geocode_admin1_polygon({province_column}, {country_column})
```
##### Insert a geocoded row into a table
```bash
UPDATE {tablename} SET the_geom = cdb_geocode_admin1_polygon('Alicante', 'Spain')
```
## City Geocoder
@ -135,16 +141,19 @@ Geometry (point, EPSG 4326) or null
##### Select
```bash
SELECT cdb_geocode_namedplace_point('Barcelona')
```
##### Update
##### Update the geometry of a table to geocode it
```bash
UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column})
```
##### Insert a geocoded row into a table
```bash
UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point('Barcelona')
```
### cdb_geocode_namedplace_point(_city_name text, country_name text_)
Geocodes the text name of a city for a specified country into a named place point geometry.
@ -162,18 +171,19 @@ Geometry (point, EPSG 4326) or null
#### Example
##### Select
```bash
SELECT cdb_geocode_namedplace_point('Barcelona', 'Spain')
```
##### Update
##### Update the geometry of a table to geocode it
```bash
UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column}, 'Spain')
```
##### Insert a geocoded row into a table
```bash
UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point('Barcelona', 'Spain')
```
### cdb_geocode_namedplace_point(_city_name text, admin1_name text, country_name text_)
Geocodes your data into a named place point geometry, containing the text name of a city, for a specified province/state and country. This is recommended for the most accurate geocoding of city data.
@ -191,18 +201,18 @@ Geometry (point, EPSG 4326) or null
#### Example
##### Select
```bash
SELECT cdb_geocode_namedplace_point('New York', 'New York', 'USA')
```
##### Update
##### Update the geometry of a table to geocode it
```bash
UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column}, {province_column}, 'USA')
```
##### Insert a geocoded row into a table
```bash
UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point('New York', 'New York', 'USA')
```
## Postal Code Geocoder
This function geocodes your data into point, or polygon, geometries for postal codes. The postal code polygon geocoder covers the United States, France, Australia and Canada; a request for a different country will return an empty response.
@ -226,18 +236,18 @@ Geometry (polygon, EPSG 4326) or null
#### Example
##### Select
```bash
SELECT cdb_geocode_postalcode_polygon('11211', 'USA')
```
##### Update
##### Update the geometry of a table to geocode it
```bash
UPDATE {tablename} SET the_geom = cdb_geocode_postalcode_polygon({postal_code_column}, 'USA')
```
##### Insert a geocoded row into a table
```bash
UPDATE {tablename} SET the_geom = cdb_geocode_postalcode_polygon('11211', 'USA')
```
### cdb_geocode_postalcode_point(_code text, country_name text_)
Goecodes the postal code for a specified country into a **point** geometry.
@ -255,18 +265,19 @@ Geometry (point, EPSG 4326) or null
#### Example
##### Select
```bash
SELECT cdb_geocode_postalcode_point('11211', 'USA')
```
##### Update
##### Update the geometry of a table to geocode it
```bash
UPDATE {tablename} SET the_geom = cdb_geocode_postalcode_point({postal_code_column}, 'USA')
```
##### Insert a geocoded row into a table
```bash
UPDATE {tablename} SET the_geom = cdb_geocode_postalcode_point('11211', 'USA')
```
## IP Addresses Geocoder
This function geocodes your data into point geometries for IP addresses. This is useful if you are analyzing location based data, based on a set of user's IP addresses.
@ -288,13 +299,13 @@ Geometry (point, EPSG 4326) or null
#### Example
##### Select
##### Update the geometry of a table to geocode it
```bash
SELECT cdb_geocode_ipaddress_point('102.23.34.1')
UPDATE {tablename} SET the_geom = cdb_geocode_ipaddress_point('102.23.34.1')
```
##### Update
##### Insert a geocoded row into a table
```bash
UPDATE {tablename} SET the_geom = cdb_geocode_ipaddress_point('102.23.34.1')