From c6358924f4933553ae4a4be59416e55e531aa82f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Carlos=20Matall=C3=ADn?= <matallo@cartodb.com>
Date: Wed, 2 Dec 2015 19:12:55 +0100
Subject: [PATCH 1/8] split files

---
 doc/API.md              | 239 +----------------------------------
 doc/general_concepts.md |  33 +++++
 doc/quickstart.md       |  21 ++++
 doc/reference.md        | 269 ++++++++++++++++++++++++++++++++++++++++
 4 files changed, 328 insertions(+), 234 deletions(-)
 create mode 100644 doc/general_concepts.md
 create mode 100644 doc/quickstart.md
 create mode 100644 doc/reference.md

diff --git a/doc/API.md b/doc/API.md
index 88d98d1..37c2b68 100644
--- a/doc/API.md
+++ b/doc/API.md
@@ -1,238 +1,9 @@
-## Geocoder API
+# Geocoder API
 
-### Overview
 The CartoDB Geocoder API allows you to match your data with geometries on your map. This geocoding service can be used programatically to geocode datasets via the CartoDB SQL API. It is fed from _Open Data_ and it serves geometries for countries, provinces, states, cities, postal codes and IP addresses.
 
-### Quickstart
-If you are using the set of APIs and libraries that CartoDB offers and you are handling your data with the SQL API, you can make your data visible in your maps by geocoding the dataset programatically.
-
-Here's an example of how to geocode a single country:
-
-```bash
-https://{username}.cartodb.com/api/v2/sql?q=SELECT cdb_geocode_admin0_polygon('USA')&api_key={Your API key}
-```
-
-In order to geocode an existent CartoDB dataset, an SQL UPDATE statement must be used to populate the geometry column in the dataset with the results of the Geocoding API. If the column in which we are storing the country names for each one of our rows is called `country_column`, we can run the following statement in order to geocode the dataset:
-
-```bash
-https://{username}.cartodb.com/api/v2/sql?q=UPDATE {tablename} SET the_geom = cdb_geocode_admin0_polygon({country_column})&api_key={Your API key}
-```
-
-Notice that you can make use of Postgres or PostGIS functions in your Geocoder API requests, as the result of it will be a geometry that can be handled by the system. As an example, if you need to retrieve the centroid of a specific country, you can wrap the resulting geometry from the Geocoder API inside the PostGIS `ST_Centroid` function:
-
-```bash
-https://{username}.cartodb.com/api/v2/sql?q=SELECT ST_Centroid(cdb_geocode_admin0_polygon('USA'))&api_key={Your API key}
-```
-
-### General concepts
-The Geocoder API offers geocoding services on top of the CartoDB SQL API by means of a set of geocoding functions. Each one of these functions is oriented to one kind of geocoding operation and it will return the corresponding geometry (a `polygon` or a `point`) according to the input information.
-
-The Geocoder API decouples the geocoding service from the CartoDB Editor, and allows to geocode data (being single rows, complete datasets or simple inputs) programatically through authenticated requests.
-
-The geometries provided by this API are projected in the projection [WGS 84 SRID 4326](http://spatialreference.org/ref/epsg/wgs-84/).
-
-The Geocoder API can return different types of geometries (points or polygons) as result of different geocoding processes. The CartoDB platform does not support multigeometry layers or datasets, therefore the final users of this Geocoder API must check that they are using consistent geometry types inside a table to avoid further conflicts in the map visualization.
-
-#### Authentication
-All requests performed to the CartoDB Geocoder API must be authenticated with the user API Key. For more information about where to find your API Key and how to authenticate your SQL API requests, check the [SQL API authentication(http://docs.cartodb.com/cartodb-platform/sql-api/authentication/) guide.
-
-#### Errors
-Errors will be described in the response of the geocoder request. An example is as follows:
-
-  ```json
-  {
-     error: [
-          "function cdb_geocode_countries(text) does not exist"
-     ]
-  }
-  ```
-
-Due to the fact that the Geocoder API is used on top of the CartoDB SQL API you can check the [Making calls to the SQL API](http://docs.cartodb.com/cartodb-platform/sql-api/making-calls/) section to help you debug your SQL errors.
-
-If the requested information is not in the CartoDB geocoding database, or if CartoDB is unable of recognizing your input and matching it with a result, the geocoding function will return `null` as a result. 
-
-#### Limits
-The usage of the Geocoder API is subject to the CartoDB SQL API limits stated in our [Terms of Service](https://cartodb.com/terms/#excessive).
-
-### Reference
-#### Geocoding functions
-The available geocoding functions are listed below, grouped by categories.
-
-##### Country geocoder
-This function provides a country geocoding service. It recognizes the names of the different countries from different synonyms, such as their English name, their endonym, or their ISO2 or ISO3 codes. 
-
-###### cdb_geocode_admin0_polygon
-
-  * `cdb_geocode_admin0_polygon(country_name text)`
-     * **Parameters**: 
-        * Name: `country_name` Type: `text` Description: Name of the country
-     * **Return type:** Geometry (polygon)
-     * **Usage example:**
-     
-       SELECT
-       `````
-       SELECT cdb_geocode_admin0_polygon('France')
-       `````
-
-       UPDATE
-       `````
-       UPDATE {tablename} SET {the_geom} = cdb_geocode_admin0_polygon({country_column})
-       `````
-
-#### Level-1 Administrative regions geocoder
-The following functions provide a geocoding service for administrative regions of level 1 (or NUTS-1) such as states for the United States, regions in France or autonomous communities in Spain.
-
-###### cdb_geocode_admin1_polygon
-* Functions: 
-  * `cdb_geocode_admin1_polygon(admin1_name text)`
-    * **Parameters**: 
-        * Name: `admin1_name` Type: `text` Description: Name of the province/state
-    * **Return type:** Geometry (polygon)
-    * **Usage example:**
-    
-      SELECT
-      `````
-      SELECT cdb_geocode_admin1_polygon('Alicante')
-      `````
-
-      UPDATE
-      `````
-      UPDATE {tablename} SET the_geom = cdb_geocode_admin1_polygon({province_column})
-      `````
-
-  *  `cdb_geocode_admin1_polygon(admin1_name text, country_name text)`
-    * **Parameters**: 
-        * Name: `admin1_name` Type: `text` Description: Name of the province/state
-        * Name: `country_name` Type: `text` Description: Name of the country in which the province/state is located
-    * **Return type:** `polygon`
-    * **Usage example:**
-     
-     SELECT
-      `````
-      SELECT cdb_geocode_admin1_polygon('Alicante', 'Spain')
-      `````
-
-     UPDATE
-     `````
-     UPDATE {tablename} SET the_geom = cdb_geocode_admin1_polygon({province_column}, {country_column})
-     `````
-
-#### City geocoder
-The following functions provide a city geocoder service. It is recommended to use the more specific geocoding function -- the one that requires more parameters -- in order for the result to be as accurate as possible when several cities share their name.
-
-##### cdb_geocode_namedplace_point
-* Functions:
-  *  `cdb_geocode_namedplace_point(city_name text)`
-    * **Parameters**: 
-        * Name: `city_name` Type: `text` Description: Name of the city
-    * **Return type:** Geometry (point)
-    * **Usage example:**
-    
-      SELECT
-      `````
-      SELECT cdb_geocode_namedplace_point('Barcelona')
-      `````
-
-      UPDATE
-      `````
-      UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column})
-      `````
-
-  *  `cdb_geocode_namedplace_point(city_name text, country_name text)`
-    * **Parameters**: 
-        * Name: `city_name` Type: `text` Description: Name of the city
-        * Name: `country_name` Type: `text` Description: Name of the country in which the city is located
-    * **Return type:** Geometry (point)
-    * **Usage example:**
-    
-      SELECT
-      `````
-      SELECT cdb_geocode_namedplace_point('Barcelona', 'Spain')
-      `````
-
-      UPDATE
-      `````
-      UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column}, 'Spain')
-      `````
-      
-  *  `cdb_geocode_namedplace_point(city_name text, admin1_name text, country_name text)`
-    * **Parameters**: 
-        * Name: `city_name` Type: `text` Description: Name of the city
-        * Name: `admin1_name` Type: `text` Description: Name of the province/state in which the city is located
-        * Name: `country_name` Type: `text` Description: Name of the country in which the city is located
-    * **Return type:** Geometry (point)
-    * **Usage example:**
-      `````
-      SELECT cdb_geocode_namedplace_point('New York', 'New York', 'USA')
-      `````
-
-      UPDATE
-      `````
-      UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column}, {province_column}, 'Spain')
-      `````
-      
-
-#### Postal codes geocoder
-The following functions provide a postal code geocoding service that can be used to obtain points or polygon results. The postal code polygon geocoder covers the United States, France, Australia and Canada; a request for a different country will return an empty response.
-
-##### cdb_geocode_postalcode_polygon
-* Functions:
-  * `cdb_geocode_postalcode_polygon(postal_code text, country_name text)`
-    * **Parameters**: 
-        * Name: `postal_code` Type: `text` Description: Postal code
-        * Name: `country_name` Type: `text` Description: Name of the country in which the postal code is located
-    * **Return type:** Geometry (polygon)
-    * **Usage example:**
-        `````
-      SELECT cdb_geocode_postalcode_polygon('11211', 'USA')
-      `````
-
-      UPDATE
-      `````
-      UPDATE {tablename} SET the_geom = cdb_geocode_postalcode_polygon({postal_code_column}, 'Spain')
-      `````
-
-** Note: For the USA, US Census ZCTAs are considered.
-
-##### cdb_geocode_postalcode_point
-* Functions:
-  * `cdb_geocode_postalcode_point(code text, country_name text)`
-    * **Parameters**: 
-        * Name: `postal_code` Type: `text` Description: Postal code
-        * Name: `country_name` Type: `text` Description: Name of the country in which the postal code is located
-    * **Return type:** Geometry (point)
-    * **Usage example:**
-        `````
-      SELECT cdb_geocode_postalcode_point('11211', 'USA')
-      `````
-
-      UPDATE
-      `````
-      UPDATE {tablename} SET the_geom = cdb_geocode_postalcode_point({postal_code_column}, 'United States')
-      `````
-
-#### IP addresses Geocoder
-This function provides an IP address geocoding service, for both IPv4 and IPv6 addresses.
-
-##### cdb_geocode_ipaddress_point
-* Functions:
-  * `cdb_geocode_ipaddress_point(ip_address text)`
-    * **Parameters**: 
-        * Name: `ip_address` Type: `text` Description: IPv4 or IPv6 address
-    * **Return type:** Geometry (point)
-    * **Usage example:**
-        `````
-      SELECT cdb_geocode_ipaddress_point('102.23.34.1')
-      `````
-
-      UPDATE
-      `````
-      UPDATE {tablename} SET the_geom = cdb_geocode_ipaddress_point('102.23.34.1')
-      `````
-
-
-
-
-
-
+## Documentation
 
+* [Quickstart](quickstart.md)
+* [General concepts](general_concepts.md)
+* [Reference](reference.md)
diff --git a/doc/general_concepts.md b/doc/general_concepts.md
new file mode 100644
index 0000000..42d562f
--- /dev/null
+++ b/doc/general_concepts.md
@@ -0,0 +1,33 @@
+# General concepts
+
+The Geocoder API offers geocoding services on top of the CartoDB SQL API by means of a set of geocoding functions. Each one of these functions is oriented to one kind of geocoding operation and it will return the corresponding geometry (a `polygon` or a `point`) according to the input information.
+
+The Geocoder API decouples the geocoding service from the CartoDB Editor, and allows to geocode data (being single rows, complete datasets or simple inputs) programatically through authenticated requests.
+
+The geometries provided by this API are projected in the projection [WGS 84 SRID 4326](http://spatialreference.org/ref/epsg/wgs-84/).
+
+The Geocoder API can return different types of geometries (points or polygons) as result of different geocoding processes. The CartoDB platform does not support multigeometry layers or datasets, therefore the final users of this Geocoder API must check that they are using consistent geometry types inside a table to avoid further conflicts in the map visualization.
+
+#### Authentication
+
+All requests performed to the CartoDB Geocoder API must be authenticated with the user API Key. For more information about where to find your API Key, and how to authenticate your SQL API requests, view the [SQL API authentication](/cartodb-platform/sql-api/authentication/) guide.
+
+#### Errors
+
+Errors are described in the response of the geocoder request. An example is as follows:
+
+```json
+{
+  error: [
+    "function cdb_geocode_countries(text) does not exist"
+  ]
+}
+```
+
+Since the Geocoder API is used on top of the CartoDB SQL API, you can refer to the [Making calls to the SQL API](/cartodb-platform/sql-api/making-calls/) documentation for help debugging your SQL errors.
+
+If the requested information is not in the CartoDB geocoding database, or if CartoDB is unable to recognize your input and match it with a result, the geocoding function returns `null` as a result.
+
+#### Limits
+
+Usage of the Geocoder API is subject to the CartoDB SQL API limits, stated in our [Terms of Service](https://cartodb.com/terms/#excessive).
diff --git a/doc/quickstart.md b/doc/quickstart.md
new file mode 100644
index 0000000..d9758ba
--- /dev/null
+++ b/doc/quickstart.md
@@ -0,0 +1,21 @@
+# Quickstart
+
+If you are using the set of APIs and libraries that CartoDB offers, and you are handling your data with the SQL API, you can make your data visible in your maps by geocoding the dataset programatically.
+
+Here is an example of how to geocode a single country:
+
+```bash
+https://{username}.cartodb.com/api/v2/sql?q=SELECT cdb_geocode_admin0_polygon('USA')&api_key={Your API key}
+```
+
+In order to geocode an existent CartoDB dataset, an SQL UPDATE statement must be used to populate the geometry column in the dataset with the results of the Geocoding API. For example, if the column where you are storing the country names for each one of our rows is called `country_column`, run the following statement in order to geocode the dataset:
+
+```bash
+https://{username}.cartodb.com/api/v2/sql?q=UPDATE {tablename} SET the_geom = cdb_geocode_admin0_polygon({country_column})&api_key={Your API key}
+```
+
+Notice that you can make use of Postgres or PostGIS functions in your Geocoder API requests, as the result of it will be a geometry that can be handled by the system. As an example, if you need to retrieve the centroid of a specific country, you can wrap the resulting geometry from the Geocoder API inside the PostGIS `ST_Centroid` function:
+
+```bash
+https://{username}.cartodb.com/api/v2/sql?q=SELECT ST_Centroid(cdb_geocode_admin0_polygon('USA'))&api_key={Your API key}
+```
diff --git a/doc/reference.md b/doc/reference.md
new file mode 100644
index 0000000..6bef656
--- /dev/null
+++ b/doc/reference.md
@@ -0,0 +1,269 @@
+# Geocoding functions
+
+The following geocoding functions are available, grouped by categories.
+
+
+## Country geocoder
+
+This function provides a country geocoding service. It recognizes the names of the different countries from different synonyms, such as their English name, their endonym, or their ISO2 or ISO3 codes.
+
+### cdb_geocode_admin0_polygon(_country_name text_)
+
+#### Arguments
+
+Name | Type | Description
+--- | --- | ---
+`cdb_geocode_admin0_polygon(country_name text)` | `text` | Name of the country
+
+#### Returns
+
+Geometry (polygon)
+
+#### Example
+
+- **Select**
+
+    ```
+    SELECT cdb_geocode_admin0_polygon('France')
+    ```
+
+- **Update**
+
+    ```
+    UPDATE {tablename} SET {the_geom} = cdb_geocode_admin0_polygon({country_column})
+    ```
+
+
+## Level-1 Administrative regions geocoder
+
+The following functions provide a geocoding service for administrative regions of level 1 (or NUTS-1) such as states for the United States, regions in France or autonomous communities in Spain.
+
+### cdb_geocode_admin1_polygon(admin1_name text_)
+
+#### Arguments
+
+Name | Type | Description
+--- | --- | ---
+`admin1_name` | `text` | Name of the province/state
+
+#### Returns
+
+Geometry (polygon)
+
+#### Example
+
+- **Select**
+
+    ```
+    SELECT cdb_geocode_admin1_polygon('Alicante', 'Spain')
+    ```
+
+- **Update**
+
+    ```
+    UPDATE {tablename} SET the_geom = cdb_geocode_admin1_polygon({province_column}, {country_column})
+    ```
+
+### cdb_geocode_admin1_polygon(admin1_name text, country_name text_)
+
+#### Arguments
+
+Name | Type | Description
+--- | --- | ---
+`admin1_name` | `text` | Name of the province/state
+`country_name` | `text` | Name of the country in which the province/state is located
+
+#### Returns
+
+polygon
+
+#### Example
+
+- **Select**
+
+    ```
+    SELECT cdb_geocode_admin1_polygon('Alicante', 'Spain')
+    ```
+
+- **Update**
+
+    ```
+    UPDATE {tablename} SET the_geom = cdb_geocode_admin1_polygon({province_column}, {country_column})
+    ```
+
+
+## City geocoder
+
+The following functions provide a city geocoder service. It is recommended to use the more specific geocoding function -- the one that requires more parameters — in order for the result to be as accurate as possible when several cities share their name.
+
+### cdb_geocode_namedplace_point(_city_name text_)
+
+#### Arguments
+
+Name | Type | Description
+--- | --- | ---
+`cdb_geocode_namedplace_point(city_name text)` | `text` | Name of the city
+
+#### Returns
+
+Geometry (point)
+
+#### Example
+
+- **Select**
+
+    ```
+    SELECT cdb_geocode_namedplace_point('Barcelona')
+    ```
+
+- **Update**
+
+    ```
+    UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column})
+    ```
+
+### cdb_geocode_namedplace_point(_city_name text, country_name text_)
+
+#### Arguments
+
+Name | Type | Description
+--- | --- | ---
+`city_name` | `text` | Name of the city
+`country_name` | `text` | Name of the country in which the city is located
+
+#### Returns
+
+Geometry (point)
+
+#### Example
+
+- **Select**
+
+    ```
+    SELECT cdb_geocode_namedplace_point('Barcelona', 'Spain')
+    ```
+
+- **Update**
+
+    ```
+    UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column}, 'Spain')
+    ```
+
+### cdb_geocode_namedplace_point(_city_name text, admin1_name text, country_name text_)
+
+#### Arguments
+
+Name | Type | Description
+--- | --- | ---
+`city_name` | `text` | Name of the city
+`admin1_name` | `text` | Name of the province/state in which the city is located
+`country_name` | `text` | Name of the country in which the city is located
+
+#### Returns
+
+Geometry (point)
+
+#### Example
+
+- **Select**
+
+    ```
+    SELECT cdb_geocode_namedplace_point('New York', 'New York', 'USA')
+    ```
+
+- **Update**
+
+    ```
+    UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column}, {province_column}, 'Spain')
+    ```
+
+## Postal codes geocoder
+
+The following functions provide a postal code geocoding service that can be used to obtain points or polygon results. The postal code polygon geocoder covers the United States, France, Australia and Canada; a request for a different country will return an empty response.
+
+### cdb_geocode_postalcode_polygon(_postal_code text, country_name text_)
+
+#### Arguments
+
+Name | Type | Description
+--- | --- | ---
+`postal_code` | `text` | Postal code
+`country_name` | `text` | Name of the country in which the postal code is located
+
+#### Returns
+
+Geometry (polygon)
+
+#### Example
+
+- **Select**
+
+    ```
+    SELECT cdb_geocode_postalcode_polygon('11211', 'USA')
+    ```
+
+- **Update**
+
+    ```
+    UPDATE {tablename} SET the_geom = cdb_geocode_postalcode_polygon({postal_code_column}, 'Spain')
+    ```
+
+**Note:** For the USA, US Census ZCTAs are considered.
+
+### cdb_geocode_postalcode_point(_code text, country_name text_)
+
+#### Arguments
+
+Name | Type | Description
+--- | --- | ---
+`postal_code` | `text` | Postal code
+`country_name` | `text` | Name of the country in which the postal code is located
+
+#### Returns
+
+Geometry (point)
+
+#### Example
+
+- **Select**
+
+    ```
+    SELECT cdb_geocode_postalcode_point('11211', 'USA')
+    ```
+
+- **Update**
+
+    ```
+    UPDATE {tablename} SET the_geom = cdb_geocode_postalcode_point({postal_code_column}, 'United States')
+    ```
+
+## IP addresses Geocoder
+
+This function provides an IP address geocoding service, for both IPv4 and IPv6 addresses.
+
+### cdb_geocode_ipaddress_point(_ip_address text_)
+
+#### Arguments
+
+Name | Type | Description
+--- | --- | ---
+`ip_address` | `text` | Postal code
+`country_name` | `text` | IPv4 or IPv6 address
+
+#### Returns
+
+Geometry (point)
+
+#### Example
+
+- **Select**
+
+    ```
+    SELECT cdb_geocode_ipaddress_point('102.23.34.1')
+    ```
+
+- **Update**
+
+    ```
+    UPDATE {tablename} SET the_geom = cdb_geocode_ipaddress_point('102.23.34.1')
+    ```

From 0288858d5a5b84e681500079b4fb33d36377b7e3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Carlos=20Matall=C3=ADn?= <matallo@cartodb.com>
Date: Wed, 2 Dec 2015 19:36:05 +0100
Subject: [PATCH 2/8] split files

---
 doc/general_concepts.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/general_concepts.md b/doc/general_concepts.md
index 42d562f..7ce7c44 100644
--- a/doc/general_concepts.md
+++ b/doc/general_concepts.md
@@ -8,11 +8,11 @@ The geometries provided by this API are projected in the projection [WGS 84 SRID
 
 The Geocoder API can return different types of geometries (points or polygons) as result of different geocoding processes. The CartoDB platform does not support multigeometry layers or datasets, therefore the final users of this Geocoder API must check that they are using consistent geometry types inside a table to avoid further conflicts in the map visualization.
 
-#### Authentication
+## Authentication
 
 All requests performed to the CartoDB Geocoder API must be authenticated with the user API Key. For more information about where to find your API Key, and how to authenticate your SQL API requests, view the [SQL API authentication](/cartodb-platform/sql-api/authentication/) guide.
 
-#### Errors
+## Errors
 
 Errors are described in the response of the geocoder request. An example is as follows:
 
@@ -28,6 +28,6 @@ Since the Geocoder API is used on top of the CartoDB SQL API, you can refer to t
 
 If the requested information is not in the CartoDB geocoding database, or if CartoDB is unable to recognize your input and match it with a result, the geocoding function returns `null` as a result.
 
-#### Limits
+## Limits
 
 Usage of the Geocoder API is subject to the CartoDB SQL API limits, stated in our [Terms of Service](https://cartodb.com/terms/#excessive).

From 7fc6f7e17350dca4e8d617847deaea5c2a568f69 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Carlos=20Matall=C3=ADn?= <matallo@cartodb.com>
Date: Wed, 2 Dec 2015 19:41:52 +0100
Subject: [PATCH 3/8] split files

---
 doc/reference.md | 36 ++++++++++++++++++------------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/doc/reference.md b/doc/reference.md
index 6bef656..135bf48 100644
--- a/doc/reference.md
+++ b/doc/reference.md
@@ -23,13 +23,13 @@ Geometry (polygon)
 
 - **Select**
 
-    ```
+    ```sql
     SELECT cdb_geocode_admin0_polygon('France')
     ```
 
 - **Update**
 
-    ```
+    ```sql
     UPDATE {tablename} SET {the_geom} = cdb_geocode_admin0_polygon({country_column})
     ```
 
@@ -54,13 +54,13 @@ Geometry (polygon)
 
 - **Select**
 
-    ```
+    ```sql
     SELECT cdb_geocode_admin1_polygon('Alicante', 'Spain')
     ```
 
 - **Update**
 
-    ```
+    ```sql
     UPDATE {tablename} SET the_geom = cdb_geocode_admin1_polygon({province_column}, {country_column})
     ```
 
@@ -81,13 +81,13 @@ polygon
 
 - **Select**
 
-    ```
+    ```sql
     SELECT cdb_geocode_admin1_polygon('Alicante', 'Spain')
     ```
 
 - **Update**
 
-    ```
+    ```sql
     UPDATE {tablename} SET the_geom = cdb_geocode_admin1_polygon({province_column}, {country_column})
     ```
 
@@ -112,13 +112,13 @@ Geometry (point)
 
 - **Select**
 
-    ```
+    ```sql
     SELECT cdb_geocode_namedplace_point('Barcelona')
     ```
 
 - **Update**
 
-    ```
+    ```sql
     UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column})
     ```
 
@@ -139,13 +139,13 @@ Geometry (point)
 
 - **Select**
 
-    ```
+    ```sql
     SELECT cdb_geocode_namedplace_point('Barcelona', 'Spain')
     ```
 
 - **Update**
 
-    ```
+    ```sql
     UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column}, 'Spain')
     ```
 
@@ -167,13 +167,13 @@ Geometry (point)
 
 - **Select**
 
-    ```
+    ```sql
     SELECT cdb_geocode_namedplace_point('New York', 'New York', 'USA')
     ```
 
 - **Update**
 
-    ```
+    ```sql
     UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column}, {province_column}, 'Spain')
     ```
 
@@ -198,13 +198,13 @@ Geometry (polygon)
 
 - **Select**
 
-    ```
+    ```sql
     SELECT cdb_geocode_postalcode_polygon('11211', 'USA')
     ```
 
 - **Update**
 
-    ```
+    ```sql
     UPDATE {tablename} SET the_geom = cdb_geocode_postalcode_polygon({postal_code_column}, 'Spain')
     ```
 
@@ -227,13 +227,13 @@ Geometry (point)
 
 - **Select**
 
-    ```
+    ```sql
     SELECT cdb_geocode_postalcode_point('11211', 'USA')
     ```
 
 - **Update**
 
-    ```
+    ```sql
     UPDATE {tablename} SET the_geom = cdb_geocode_postalcode_point({postal_code_column}, 'United States')
     ```
 
@@ -258,12 +258,12 @@ Geometry (point)
 
 - **Select**
 
-    ```
+    ```sql
     SELECT cdb_geocode_ipaddress_point('102.23.34.1')
     ```
 
 - **Update**
 
-    ```
+    ```sql
     UPDATE {tablename} SET the_geom = cdb_geocode_ipaddress_point('102.23.34.1')
     ```

From 2ff102361df96c5df15371781b4655a684af54f3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Carlos=20Matall=C3=ADn?= <matallo@cartodb.com>
Date: Wed, 2 Dec 2015 19:47:28 +0100
Subject: [PATCH 4/8] split files

---
 doc/reference.md | 108 +++++++++++++++++++++++------------------------
 1 file changed, 54 insertions(+), 54 deletions(-)

diff --git a/doc/reference.md b/doc/reference.md
index 135bf48..694bd03 100644
--- a/doc/reference.md
+++ b/doc/reference.md
@@ -23,15 +23,15 @@ Geometry (polygon)
 
 - **Select**
 
-    ```sql
-    SELECT cdb_geocode_admin0_polygon('France')
-    ```
+```sql
+SELECT cdb_geocode_admin0_polygon('France')
+```
 
 - **Update**
 
-    ```sql
-    UPDATE {tablename} SET {the_geom} = cdb_geocode_admin0_polygon({country_column})
-    ```
+```sql
+UPDATE {tablename} SET {the_geom} = cdb_geocode_admin0_polygon({country_column})
+```
 
 
 ## Level-1 Administrative regions geocoder
@@ -54,15 +54,15 @@ Geometry (polygon)
 
 - **Select**
 
-    ```sql
-    SELECT cdb_geocode_admin1_polygon('Alicante', 'Spain')
-    ```
+```sql
+SELECT cdb_geocode_admin1_polygon('Alicante', 'Spain')
+```
 
 - **Update**
 
-    ```sql
-    UPDATE {tablename} SET the_geom = cdb_geocode_admin1_polygon({province_column}, {country_column})
-    ```
+```sql
+UPDATE {tablename} SET the_geom = cdb_geocode_admin1_polygon({province_column}, {country_column})
+```
 
 ### cdb_geocode_admin1_polygon(admin1_name text, country_name text_)
 
@@ -81,15 +81,15 @@ polygon
 
 - **Select**
 
-    ```sql
-    SELECT cdb_geocode_admin1_polygon('Alicante', 'Spain')
-    ```
+```sql
+SELECT cdb_geocode_admin1_polygon('Alicante', 'Spain')
+```
 
 - **Update**
 
-    ```sql
-    UPDATE {tablename} SET the_geom = cdb_geocode_admin1_polygon({province_column}, {country_column})
-    ```
+```sql
+UPDATE {tablename} SET the_geom = cdb_geocode_admin1_polygon({province_column}, {country_column})
+```
 
 
 ## City geocoder
@@ -112,15 +112,15 @@ Geometry (point)
 
 - **Select**
 
-    ```sql
-    SELECT cdb_geocode_namedplace_point('Barcelona')
-    ```
+```sql
+SELECT cdb_geocode_namedplace_point('Barcelona')
+```
 
 - **Update**
 
-    ```sql
-    UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column})
-    ```
+```sql
+UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column})
+```
 
 ### cdb_geocode_namedplace_point(_city_name text, country_name text_)
 
@@ -139,15 +139,15 @@ Geometry (point)
 
 - **Select**
 
-    ```sql
-    SELECT cdb_geocode_namedplace_point('Barcelona', 'Spain')
-    ```
+```sql
+SELECT cdb_geocode_namedplace_point('Barcelona', 'Spain')
+```
 
 - **Update**
 
-    ```sql
-    UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column}, 'Spain')
-    ```
+```sql
+UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column}, 'Spain')
+```
 
 ### cdb_geocode_namedplace_point(_city_name text, admin1_name text, country_name text_)
 
@@ -167,15 +167,15 @@ Geometry (point)
 
 - **Select**
 
-    ```sql
-    SELECT cdb_geocode_namedplace_point('New York', 'New York', 'USA')
-    ```
+```sql
+SELECT cdb_geocode_namedplace_point('New York', 'New York', 'USA')
+```
 
 - **Update**
 
-    ```sql
-    UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column}, {province_column}, 'Spain')
-    ```
+```sql
+UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column}, {province_column}, 'Spain')
+```
 
 ## Postal codes geocoder
 
@@ -198,15 +198,15 @@ Geometry (polygon)
 
 - **Select**
 
-    ```sql
-    SELECT cdb_geocode_postalcode_polygon('11211', 'USA')
-    ```
+```sql
+SELECT cdb_geocode_postalcode_polygon('11211', 'USA')
+```
 
 - **Update**
 
-    ```sql
-    UPDATE {tablename} SET the_geom = cdb_geocode_postalcode_polygon({postal_code_column}, 'Spain')
-    ```
+```sql
+UPDATE {tablename} SET the_geom = cdb_geocode_postalcode_polygon({postal_code_column}, 'Spain')
+```
 
 **Note:** For the USA, US Census ZCTAs are considered.
 
@@ -227,15 +227,15 @@ Geometry (point)
 
 - **Select**
 
-    ```sql
-    SELECT cdb_geocode_postalcode_point('11211', 'USA')
-    ```
+```sql
+SELECT cdb_geocode_postalcode_point('11211', 'USA')
+```
 
 - **Update**
 
-    ```sql
-    UPDATE {tablename} SET the_geom = cdb_geocode_postalcode_point({postal_code_column}, 'United States')
-    ```
+```sql
+UPDATE {tablename} SET the_geom = cdb_geocode_postalcode_point({postal_code_column}, 'United States')
+```
 
 ## IP addresses Geocoder
 
@@ -258,12 +258,12 @@ Geometry (point)
 
 - **Select**
 
-    ```sql
-    SELECT cdb_geocode_ipaddress_point('102.23.34.1')
-    ```
+```sql
+SELECT cdb_geocode_ipaddress_point('102.23.34.1')
+```
 
 - **Update**
 
-    ```sql
-    UPDATE {tablename} SET the_geom = cdb_geocode_ipaddress_point('102.23.34.1')
-    ```
+```sql
+UPDATE {tablename} SET the_geom = cdb_geocode_ipaddress_point('102.23.34.1')
+```

From 4cf104e80c8ec209de2f8ccbe199624338eb9d8d Mon Sep 17 00:00:00 2001
From: Carla <carla@cartodb.com>
Date: Thu, 3 Dec 2015 11:01:41 +0100
Subject: [PATCH 5/8] Fix format

---
 doc/reference.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/doc/reference.md b/doc/reference.md
index 694bd03..361186b 100644
--- a/doc/reference.md
+++ b/doc/reference.md
@@ -13,7 +13,7 @@ This function provides a country geocoding service. It recognizes the names of t
 
 Name | Type | Description
 --- | --- | ---
-`cdb_geocode_admin0_polygon(country_name text)` | `text` | Name of the country
+`country_name` | `text` | Name of the country
 
 #### Returns
 
@@ -38,7 +38,7 @@ UPDATE {tablename} SET {the_geom} = cdb_geocode_admin0_polygon({country_column})
 
 The following functions provide a geocoding service for administrative regions of level 1 (or NUTS-1) such as states for the United States, regions in France or autonomous communities in Spain.
 
-### cdb_geocode_admin1_polygon(admin1_name text_)
+### cdb_geocode_admin1_polygon(_admin1_name text_)
 
 #### Arguments
 
@@ -64,7 +64,7 @@ SELECT cdb_geocode_admin1_polygon('Alicante', 'Spain')
 UPDATE {tablename} SET the_geom = cdb_geocode_admin1_polygon({province_column}, {country_column})
 ```
 
-### cdb_geocode_admin1_polygon(admin1_name text, country_name text_)
+### cdb_geocode_admin1_polygon(_admin1_name text, country_name text_)
 
 #### Arguments
 
@@ -75,7 +75,7 @@ Name | Type | Description
 
 #### Returns
 
-polygon
+Geometry (polygon)
 
 #### Example
 
@@ -102,7 +102,7 @@ The following functions provide a city geocoder service. It is recommended to us
 
 Name | Type | Description
 --- | --- | ---
-`cdb_geocode_namedplace_point(city_name text)` | `text` | Name of the city
+`city_name` | `text` | Name of the city
 
 #### Returns
 

From 85e95e1e60e80e48c2b7e7d2142cf261852a66f6 Mon Sep 17 00:00:00 2001
From: Carla <carla@cartodb.com>
Date: Thu, 3 Dec 2015 11:24:45 +0100
Subject: [PATCH 6/8] Update reference.md

---
 doc/reference.md | 36 ++++++++++++++++++------------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/doc/reference.md b/doc/reference.md
index 361186b..d3b5a92 100644
--- a/doc/reference.md
+++ b/doc/reference.md
@@ -21,13 +21,13 @@ Geometry (polygon)
 
 #### Example
 
-- **Select**
+##### Select
 
 ```sql
 SELECT cdb_geocode_admin0_polygon('France')
 ```
 
-- **Update**
+##### Update
 
 ```sql
 UPDATE {tablename} SET {the_geom} = cdb_geocode_admin0_polygon({country_column})
@@ -52,13 +52,13 @@ Geometry (polygon)
 
 #### Example
 
-- **Select**
+##### Select
 
 ```sql
 SELECT cdb_geocode_admin1_polygon('Alicante', 'Spain')
 ```
 
-- **Update**
+##### Update
 
 ```sql
 UPDATE {tablename} SET the_geom = cdb_geocode_admin1_polygon({province_column}, {country_column})
@@ -79,13 +79,13 @@ Geometry (polygon)
 
 #### Example
 
-- **Select**
+##### Select
 
 ```sql
 SELECT cdb_geocode_admin1_polygon('Alicante', 'Spain')
 ```
 
-- **Update**
+##### Update
 
 ```sql
 UPDATE {tablename} SET the_geom = cdb_geocode_admin1_polygon({province_column}, {country_column})
@@ -110,13 +110,13 @@ Geometry (point)
 
 #### Example
 
-- **Select**
+##### Select
 
 ```sql
 SELECT cdb_geocode_namedplace_point('Barcelona')
 ```
 
-- **Update**
+##### Update
 
 ```sql
 UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column})
@@ -137,13 +137,13 @@ Geometry (point)
 
 #### Example
 
-- **Select**
+##### Select
 
 ```sql
 SELECT cdb_geocode_namedplace_point('Barcelona', 'Spain')
 ```
 
-- **Update**
+##### Update
 
 ```sql
 UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column}, 'Spain')
@@ -165,13 +165,13 @@ Geometry (point)
 
 #### Example
 
-- **Select**
+##### Select
 
 ```sql
 SELECT cdb_geocode_namedplace_point('New York', 'New York', 'USA')
 ```
 
-- **Update**
+##### Update
 
 ```sql
 UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column}, {province_column}, 'Spain')
@@ -196,13 +196,13 @@ Geometry (polygon)
 
 #### Example
 
-- **Select**
+##### Select
 
 ```sql
 SELECT cdb_geocode_postalcode_polygon('11211', 'USA')
 ```
 
-- **Update**
+##### Update
 
 ```sql
 UPDATE {tablename} SET the_geom = cdb_geocode_postalcode_polygon({postal_code_column}, 'Spain')
@@ -225,13 +225,13 @@ Geometry (point)
 
 #### Example
 
-- **Select**
+##### Select
 
 ```sql
 SELECT cdb_geocode_postalcode_point('11211', 'USA')
 ```
 
-- **Update**
+##### Update
 
 ```sql
 UPDATE {tablename} SET the_geom = cdb_geocode_postalcode_point({postal_code_column}, 'United States')
@@ -256,13 +256,13 @@ Geometry (point)
 
 #### Example
 
-- **Select**
+##### Select
 
 ```sql
 SELECT cdb_geocode_ipaddress_point('102.23.34.1')
 ```
 
-- **Update**
+##### Update
 
 ```sql
 UPDATE {tablename} SET the_geom = cdb_geocode_ipaddress_point('102.23.34.1')

From 296ded26d565c5dca40e1d4241eca7c8bfb9322a Mon Sep 17 00:00:00 2001
From: Carla <carla@cartodb.com>
Date: Fri, 4 Dec 2015 14:49:41 +0100
Subject: [PATCH 7/8] Make explicit the projection

---
 doc/reference.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/doc/reference.md b/doc/reference.md
index d3b5a92..59552be 100644
--- a/doc/reference.md
+++ b/doc/reference.md
@@ -17,7 +17,7 @@ Name | Type | Description
 
 #### Returns
 
-Geometry (polygon)
+Geometry (polygon, EPSG 4326) or null
 
 #### Example
 
@@ -48,7 +48,7 @@ Name | Type | Description
 
 #### Returns
 
-Geometry (polygon)
+Geometry (polygon, EPSG 4326) or null
 
 #### Example
 
@@ -75,7 +75,7 @@ Name | Type | Description
 
 #### Returns
 
-Geometry (polygon)
+Geometry (polygon, EPSG 4326) or null
 
 #### Example
 
@@ -106,7 +106,7 @@ Name | Type | Description
 
 #### Returns
 
-Geometry (point)
+Geometry (point, EPSG 4326) or null
 
 #### Example
 
@@ -133,7 +133,7 @@ Name | Type | Description
 
 #### Returns
 
-Geometry (point)
+Geometry (point, EPSG 4326) or null
 
 #### Example
 
@@ -161,7 +161,7 @@ Name | Type | Description
 
 #### Returns
 
-Geometry (point)
+Geometry (point, EPSG 4326) or null
 
 #### Example
 
@@ -192,7 +192,7 @@ Name | Type | Description
 
 #### Returns
 
-Geometry (polygon)
+Geometry (polygon, EPSG 4326) or null
 
 #### Example
 
@@ -221,7 +221,7 @@ Name | Type | Description
 
 #### Returns
 
-Geometry (point)
+Geometry (point, EPSG 4326) or null
 
 #### Example
 
@@ -252,7 +252,7 @@ Name | Type | Description
 
 #### Returns
 
-Geometry (point)
+Geometry (point, EPSG 4326) or null
 
 #### Example
 

From a03d3f9541f6dee576fbadf3afcef9075dbd812b Mon Sep 17 00:00:00 2001
From: Carla <carla@cartodb.com>
Date: Wed, 9 Dec 2015 13:23:59 +0100
Subject: [PATCH 8/8] edits error example

---
 doc/general_concepts.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/general_concepts.md b/doc/general_concepts.md
index 7ce7c44..1287375 100644
--- a/doc/general_concepts.md
+++ b/doc/general_concepts.md
@@ -19,7 +19,7 @@ Errors are described in the response of the geocoder request. An example is as f
 ```json
 {
   error: [
-    "function cdb_geocode_countries(text) does not exist"
+    "The api_key must be provided"
   ]
 }
 ```