split files

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')
+    ```