diff --git a/doc/geocoding_functions.md b/doc/geocoding_functions.md index d7f5dcc..7e70c38 100644 --- a/doc/geocoding_functions.md +++ b/doc/geocoding_functions.md @@ -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')