Update README.md

README for integration tests

LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2015, CartoDB
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without 
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this 
+list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, 
+this list of conditions and the following disclaimer in the documentation 
+and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors 
+may be used to endorse or promote products derived from this software without 
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

client/README.md

@@ -30,8 +30,6 @@ sudo PGUSER=postgres make all install installcheck
 
 ## Install onto a cartodb user's database
 
-Remember that **is mandatory to install it on top of cdb_geocoder**
-
 ```
 psql -U postgres cartodb_dev_user_fe3b850a-01c0-48f9-8a26-a82f09e9b53f_db
 ```

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)

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: [
+    "The api_key must be provided"
+  ]
+}
+```
+
+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).

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}
+```

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
+--- | --- | ---
+`country_name` | `text` | Name of the country
+
+#### Returns
+
+Geometry (polygon, EPSG 4326) or null
+
+#### Example
+
+##### Select
+
+```sql
+SELECT cdb_geocode_admin0_polygon('France')
+```
+
+##### Update
+
+```sql
+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, EPSG 4326) or null
+
+#### Example
+
+##### Select
+
+```sql
+SELECT cdb_geocode_admin1_polygon('Alicante', 'Spain')
+```
+
+##### Update
+
+```sql
+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
+
+Geometry (polygon, EPSG 4326) or null
+
+#### Example
+
+##### Select
+
+```sql
+SELECT cdb_geocode_admin1_polygon('Alicante', 'Spain')
+```
+
+##### Update
+
+```sql
+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
+--- | --- | ---
+`city_name` | `text` | Name of the city
+
+#### Returns
+
+Geometry (point, EPSG 4326) or null
+
+#### Example
+
+##### Select
+
+```sql
+SELECT cdb_geocode_namedplace_point('Barcelona')
+```
+
+##### Update
+
+```sql
+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, EPSG 4326) or null
+
+#### Example
+
+##### Select
+
+```sql
+SELECT cdb_geocode_namedplace_point('Barcelona', 'Spain')
+```
+
+##### Update
+
+```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_)
+
+#### 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, EPSG 4326) or null
+
+#### Example
+
+##### 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')
+```
+
+## 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, EPSG 4326) or null
+
+#### Example
+
+##### Select
+
+```sql
+SELECT cdb_geocode_postalcode_polygon('11211', 'USA')
+```
+
+##### Update
+
+```sql
+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, EPSG 4326) or null
+
+#### Example
+
+##### 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')
+```
+
+## 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, EPSG 4326) or null
+
+#### Example
+
+##### 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')
+```

test/README.md

@@ -0,0 +1,20 @@
+# Geocoder API integration tests
+This are the automatic integration tests for geocoder api (both client and server)
+
+### Usage
+In order to execute the tests you have to execute the `run_tests` python script:
+
+``` python run_tests.py [--host=cartodb.com] username api_key```
+
+You can define the host where is going to execute the SQL API queries to test the
+geocoder API. By default the value is `cartodb.com` but you can put the host you need.
+
+### Tests
+
+This suite of tests test the following parts of the geocoding API through the SQL API:
+
+- Admin 0 functions
+- Admin 1 functions
+- Named places functions
+- Postal code functions
+- Ip address functions

test/fixtures/geocoder_api_test_dataset.csv

@@ -0,0 +1,3 @@
+id,country,province,city,postalcode,ip
+1,Spain,Castilla y León,Valladolid,47010,8.8.8.8
+2,USA,New York,Manhattn,10001,8.8.8.8

test/helpers/import_helper.py

@@ -0,0 +1,59 @@
+import os
+import requests
+import json
+
+import time
+
+
+class ImportHelper:
+
+    @classmethod
+    def import_test_dataset(cls, username, api_key, host):
+        requests.packages.urllib3.disable_warnings()
+        url = "https://{0}.{1}/api/v1/imports/"\
+            "?type_guessing=false&privacy=public&api_key={2}".format(
+            username, host, api_key)
+        dataset = {
+            'file': open('fixtures/geocoder_api_test_dataset.csv', 'rb')}
+        response = requests.post(url, files=dataset)
+        response_json = json.loads(response.text)
+        if not response_json['success']:
+            print "Error importing the test dataset: {0}".format(response.text)
+            sys.exit(1)
+        while(True):
+            table_name = ImportHelper.get_imported_table_name(
+                username,
+                host,
+                api_key,
+                response_json['item_queue_id']
+            )
+            if table_name:
+                return table_name
+            else:
+                time.sleep(5)
+
+    @classmethod
+    def get_imported_table_name(cls, username, host, api_key, import_id):
+        requests.packages.urllib3.disable_warnings()
+        import_url = "https://{0}.{1}/api/v1/imports/{2}?api_key={3}".format(
+            username, host, import_id, api_key)
+        import_data_response = requests.get(import_url)
+        if import_data_response.status_code != 200:
+            print "Error getting the table name from " \
+                "the import data: {0}".format(
+                import_data_response.text)
+            sys.exit(1)
+        import_data_json = json.loads(import_data_response.text)
+
+        return import_data_json['table_name']
+
+    @classmethod
+    def clean_test_dataset(cls, username, api_key, table_name, host):
+        requests.packages.urllib3.disable_warnings()
+        url = "https://{0}.{1}/api/v2/sql?q=drop table {2}&api_key={3}".format(
+            username, host, table_name, api_key
+        )
+        response = requests.get(url)
+        if response.status_code != 200:
+            print "Error cleaning the test dataset: {0}".format(response.text)
+            sys.exit(1)

test/helpers/integration_test_helper.py

@@ -0,0 +1,32 @@
+import os
+import requests
+import json
+
+
+class IntegrationTestHelper:
+
+    @classmethod
+    def get_environment_variables(cls):
+        username = os.environ["GEOCODER_API_TEST_USERNAME"]
+        api_key = os.environ["GEOCODER_API_TEST_API_KEY"]
+        host = os.environ["GEOCODER_API_TEST_HOST"]
+        table_name = os.environ["GEOCODER_API_TEST_TABLE_NAME"]
+
+        return {
+            "username": username,
+            "api_key": api_key,
+            "host": host,
+            "table_name": table_name
+        }
+
+    @classmethod
+    def execute_query(cls, sql_api_url, query):
+        requests.packages.urllib3.disable_warnings()
+        query_url = "{0}?q={1}".format(sql_api_url, query)
+        print "Executing query: {0}".format(query_url)
+        query_response = requests.get(query_url)
+        if query_response.status_code != 200:
+            raise Exception(json.loads(query_response.text)['error'])
+        query_response_data = json.loads(query_response.text)
+
+        return query_response_data['rows'][0]['geometry']

test/integration/test_admin0_functions.py

@@ -0,0 +1,32 @@
+from unittest import TestCase
+from nose.tools import assert_raises
+from nose.tools import assert_not_equal, assert_equal
+from ..helpers.integration_test_helper import IntegrationTestHelper
+
+
+class TestAdmin0Functions(TestCase):
+
+    def setUp(self):
+        self.env_variables = IntegrationTestHelper.get_environment_variables()
+        self.sql_api_url = "https://{0}.{1}/api/v2/sql".format(
+            self.env_variables['username'],
+            self.env_variables['host'],
+            self.env_variables['api_key']
+        )
+
+    def test_if_select_with_admin0_is_ok(self):
+        query = "SELECT cdb_geocode_admin0_polygon(country) as geometry " \
+            "FROM {0} LIMIT 1&api_key={1}".format(
+            self.env_variables['table_name'],
+            self.env_variables['api_key'])
+        geometry = IntegrationTestHelper.execute_query(self.sql_api_url, query)
+        assert_not_equal(geometry, None)
+
+    def test_if_select_with_admin0_without_api_key_raise_error(self):
+        query = "SELECT cdb_geocode_admin0_polygon(country) as geometry " \
+            "FROM {0} LIMIT 1".format(
+            self.env_variables['table_name'])
+        try:
+            IntegrationTestHelper.execute_query(self.sql_api_url, query)
+        except Exception as e:
+            assert_equal(e.message[0], "The api_key must be provided")

test/integration/test_admin1_functions.py

@@ -0,0 +1,40 @@
+from unittest import TestCase
+from nose.tools import assert_raises
+from nose.tools import assert_not_equal, assert_equal
+from ..helpers.integration_test_helper import IntegrationTestHelper
+
+
+class TestAdmin1Functions(TestCase):
+
+    def setUp(self):
+        self.env_variables = IntegrationTestHelper.get_environment_variables()
+        self.sql_api_url = "https://{0}.{1}/api/v2/sql".format(
+            self.env_variables['username'],
+            self.env_variables['host'],
+            self.env_variables['api_key']
+        )
+
+    def test_if_select_with_admin1_without_country_is_ok(self):
+        query = "SELECT cdb_geocode_admin1_polygon(province) as geometry " \
+            "FROM {0} LIMIT 1&api_key={1}".format(
+            self.env_variables['table_name'],
+            self.env_variables['api_key'])
+        geometry = IntegrationTestHelper.execute_query(self.sql_api_url, query)
+        assert_not_equal(geometry, None)
+
+    def test_if_select_with_admin1_with_country_is_ok(self):
+        query = "SELECT cdb_geocode_admin1_polygon(province,country)" \
+            "as geometry FROM {0} LIMIT 1&api_key={1}".format(
+            self.env_variables['table_name'],
+            self.env_variables['api_key'])
+        geometry = IntegrationTestHelper.execute_query(self.sql_api_url, query)
+        assert_not_equal(geometry, None)
+
+    def test_if_select_with_admin1_without_api_key_raise_error(self):
+        query = "SELECT cdb_geocode_admin1_polygon(province) as geometry " \
+            "FROM {0} LIMIT 1".format(
+            self.env_variables['table_name'])
+        try:
+            IntegrationTestHelper.execute_query(self.sql_api_url, query)
+        except Exception as e:
+            assert_equal(e.message[0], "The api_key must be provided")

test/integration/test_ipaddress_functions.py

@@ -0,0 +1,32 @@
+from unittest import TestCase
+from nose.tools import assert_raises
+from nose.tools import assert_not_equal, assert_equal
+from ..helpers.integration_test_helper import IntegrationTestHelper
+
+
+class TestPostalcodeFunctions(TestCase):
+
+    def setUp(self):
+        self.env_variables = IntegrationTestHelper.get_environment_variables()
+        self.sql_api_url = "https://{0}.{1}/api/v2/sql".format(
+            self.env_variables['username'],
+            self.env_variables['host'],
+            self.env_variables['api_key']
+        )
+
+    def test_if_select_with_ipaddress_point_is_ok(self):
+        query = "SELECT cdb_geocode_ipaddress_point(ip) " \
+            "as geometry FROM {0} LIMIT 1&api_key={1}".format(
+            self.env_variables['table_name'],
+            self.env_variables['api_key'])
+        geometry = IntegrationTestHelper.execute_query(self.sql_api_url, query)
+        assert_not_equal(geometry, None)
+
+    def test_if_select_with_ipaddress_without_api_key_raise_error(self):
+        query = "SELECT cdb_geocode_ipaddress_point(ip) " \
+            "as geometry FROM {0} LIMIT 1".format(
+            self.env_variables['table_name'])
+        try:
+            IntegrationTestHelper.execute_query(self.sql_api_url, query)
+        except Exception as e:
+            assert_equal(e.message[0], "The api_key must be provided")

test/integration/test_namedplace_functions.py

@@ -0,0 +1,48 @@
+from unittest import TestCase
+from nose.tools import assert_raises
+from nose.tools import assert_not_equal, assert_equal
+from ..helpers.integration_test_helper import IntegrationTestHelper
+
+
+class TestNameplaceFunctions(TestCase):
+
+    def setUp(self):
+        self.env_variables = IntegrationTestHelper.get_environment_variables()
+        self.sql_api_url = "https://{0}.{1}/api/v2/sql".format(
+            self.env_variables['username'],
+            self.env_variables['host'],
+            self.env_variables['api_key']
+        )
+
+    def test_if_select_with_namedplace_city_is_ok(self):
+        query = "SELECT cdb_geocode_namedplace_point(city) as geometry " \
+            "FROM {0} LIMIT 1&api_key={1}".format(
+            self.env_variables['table_name'],
+            self.env_variables['api_key'])
+        geometry = IntegrationTestHelper.execute_query(self.sql_api_url, query)
+        assert_not_equal(geometry, None)
+
+    def test_if_select_with_namedplace_city_country_is_ok(self):
+        query = "SELECT cdb_geocode_namedplace_point(city,country) " \
+            "as geometry FROM {0} LIMIT 1&api_key={1}".format(
+            self.env_variables['table_name'],
+            self.env_variables['api_key'])
+        geometry = IntegrationTestHelper.execute_query(self.sql_api_url, query)
+        assert_not_equal(geometry, None)
+
+    def test_if_select_with_namedplace_city_province_country_is_ok(self):
+        query = "SELECT cdb_geocode_namedplace_point(city,province,country) " \
+            "as geometry FROM {0} LIMIT 1&api_key={1}".format(
+            self.env_variables['table_name'],
+            self.env_variables['api_key'])
+        geometry = IntegrationTestHelper.execute_query(self.sql_api_url, query)
+        assert_not_equal(geometry, None)
+
+    def test_if_select_with_namedplace_without_api_key_raise_error(self):
+        query = "SELECT cdb_geocode_namedplace_point(city) as geometry " \
+            "FROM {0} LIMIT 1".format(
+            self.env_variables['table_name'])
+        try:
+            IntegrationTestHelper.execute_query(self.sql_api_url, query)
+        except Exception as e:
+            assert_equal(e.message[0], "The api_key must be provided")

test/integration/test_postalcode_functions.py

@@ -0,0 +1,40 @@
+from unittest import TestCase
+from nose.tools import assert_raises
+from nose.tools import assert_not_equal, assert_equal
+from ..helpers.integration_test_helper import IntegrationTestHelper
+
+
+class TestPostalcodeFunctions(TestCase):
+
+    def setUp(self):
+        self.env_variables = IntegrationTestHelper.get_environment_variables()
+        self.sql_api_url = "https://{0}.{1}/api/v2/sql".format(
+            self.env_variables['username'],
+            self.env_variables['host'],
+            self.env_variables['api_key']
+        )
+
+    def test_if_select_with_postalcode_polygon_is_ok(self):
+        query = "SELECT cdb_geocode_postalcode_polygon(postalcode, country) " \
+            "as geometry FROM {0} WHERE country='USA'&api_key={1}".format(
+            self.env_variables['table_name'],
+            self.env_variables['api_key'])
+        geometry = IntegrationTestHelper.execute_query(self.sql_api_url, query)
+        assert_not_equal(geometry, None)
+
+    def test_if_select_with_postalcode_point_is_ok(self):
+        query = "SELECT cdb_geocode_postalcode_point(postalcode, country) " \
+            "as geometry FROM {0} WHERE country='Spain'&api_key={1}".format(
+            self.env_variables['table_name'],
+            self.env_variables['api_key'])
+        geometry = IntegrationTestHelper.execute_query(self.sql_api_url, query)
+        assert_not_equal(geometry, None)
+
+    def test_if_select_with_postalcode_without_api_key_raise_error(self):
+        query = "SELECT cdb_geocode_postalcode_polygon(postalcode, country) " \
+            "as geometry FROM {0} WHERE country = 'USA'".format(
+            self.env_variables['table_name'])
+        try:
+            IntegrationTestHelper.execute_query(self.sql_api_url, query)
+        except Exception as e:
+            assert_equal(e.message[0], "The api_key must be provided")

test/run_tests.py

@@ -0,0 +1,76 @@
+import getopt
+import sys
+import time
+import subprocess
+import os
+import re
+from helpers.import_helper import ImportHelper
+
+
+def main():
+    opts, args = getopt.getopt(sys.argv[1:], "h", ["help", "host="])
+
+    if len(args) < 2:
+        usage()
+        sys.exit()
+
+    host = "cartodb.com"
+    username = args[0]
+    api_key = args[1]
+    table_name = "geocoder_api_test_dataset_".format(int(time.time()))
+    for o, a in opts:
+        if o in ("-h", "--help"):
+            usage()
+            sys.exit()
+        elif o in ("--host"):
+            host = opts[0][1]
+        else:
+            assert False, "unhandled option"
+
+    try:
+        table_name = ImportHelper.import_test_dataset(username, api_key, host)
+        set_environment_variables(username, api_key, table_name, host)
+        execute_tests()
+    except Exception as e:
+        print e.message
+        sys.exit(1)
+    finally:
+        clean_environment_variables()
+        ImportHelper.clean_test_dataset(username, api_key, table_name, host)
+
+
+def usage():
+    print """Usage: run_tests.py [options] username api_key
+        Options:
+        -h: Show this help
+        --host: take that host as base (by default is cartodb.com)"""
+
+
+def execute_tests():
+    process = subprocess.Popen(
+        ["nosetests", "--where=integration/"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE
+    )
+    out, err = process.communicate()
+    print err
+    regexp = re.compile(r'FAILED \(.*\)')
+    if regexp.search(err) is not None:
+        sys.exit(1)
+
+
+def set_environment_variables(username, api_key, table_name, host):
+    os.environ["GEOCODER_API_TEST_USERNAME"] = username
+    os.environ["GEOCODER_API_TEST_API_KEY"] = api_key
+    os.environ["GEOCODER_API_TEST_TABLE_NAME"] = table_name
+    os.environ["GEOCODER_API_TEST_HOST"] = host
+
+
+def clean_environment_variables():
+    del os.environ["GEOCODER_API_TEST_USERNAME"]
+    del os.environ["GEOCODER_API_TEST_API_KEY"]
+    del os.environ["GEOCODER_API_TEST_TABLE_NAME"]
+    del os.environ["GEOCODER_API_TEST_HOST"]
+
+if __name__ == "__main__":
+    main()