Remove selects from geocoding functions

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
+##### Update the geometry of a table to geocode it
-
-```bash
-SELECT cdb_geocode_admin0_polygon('France')
-```
-
-##### Update
 
 ```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
+##### Update the geometry of a table to geocode it
-
-```bash
-SELECT cdb_geocode_admin1_polygon('Alicante')
-```
-
-##### Update
 
 ```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
+##### Update the geometry of a table to geocode it
-
-```bash
-SELECT cdb_geocode_admin1_polygon('Alicante', 'Spain')
-```
-
-##### Update
 
 ```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
+##### Update the geometry of a table to geocode it
-SELECT cdb_geocode_namedplace_point('Barcelona')
-```
-
-##### Update
 
 ```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
+##### Update the geometry of a table to geocode it
-
-```bash
-SELECT cdb_geocode_namedplace_point('Barcelona', 'Spain')
-```
-
-##### Update
 
 ```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
+##### Update the geometry of a table to geocode it
-
-```bash
-SELECT cdb_geocode_namedplace_point('New York', 'New York', 'USA')
-```
-
-##### Update
 
 ```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
+##### Update the geometry of a table to geocode it
-
-```bash
-SELECT cdb_geocode_postalcode_polygon('11211', 'USA')
-```
-
-##### Update
 
 ```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
+##### Update the geometry of a table to geocode it
-
-```bash
-SELECT cdb_geocode_postalcode_point('11211', 'USA')
-```
-
-##### Update
 
 ```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')