2015-11-13 21:59:07 +08:00
## Geocoder API
### Overview
### Quickstart
### General concepts
2015-11-13 23:04:11 +08:00
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.
2015-11-13 23:06:18 +08:00
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.
2015-11-13 22:46:26 +08:00
#### Errors
2015-11-13 23:01:44 +08:00
Errors will be described in the response of the geocoder request. An example is as follows:
```json
{
error: [
"function 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.
2015-11-13 23:04:11 +08:00
#### Pre/post conditions
2015-11-13 23:01:44 +08:00
2015-11-13 22:46:26 +08:00
#### Possible side-effects
For each function:
function names
function parameters and types
return type for the functions (Geometry or NULL if not found, with SRID 4326)
2015-11-13 21:59:07 +08:00
### Reference
2015-11-13 22:22:00 +08:00
#### Geocoding functions
##### Country geocoder functions
###### geocode_admin0_polygon
2015-11-13 21:59:07 +08:00
* Description:
2015-11-13 22:22:00 +08:00
This function receives a country name and returns a polygon geometry (SRID 4326) for the corresponding input.
2015-11-13 21:59:07 +08:00
* Functions:
2015-11-13 22:22:00 +08:00
* `geocode_admin0_polygon(country_name text)`
* **Parameters**: A text parameter with the name of the country to geocode.
2015-11-13 21:59:07 +08:00
* **Return type:** `polygon`
* **Usage example:**
`````
2015-11-13 22:00:39 +08:00
SELECT geocode_admin0_polygon('France')
2015-11-13 21:59:07 +08:00
`````
2015-11-13 22:22:00 +08:00
#### Level-1 Administrative regions geocoder
###### geocode_admin1_polygon
2015-11-13 21:59:07 +08:00
* Functions:
2015-11-13 22:22:00 +08:00
* `geocode_admin1_polygon(admin1_name text)`
* **Parameters**:
* **Return type:** `polygon`
2015-11-13 21:59:07 +08:00
* **Usage example:**
`````
2015-11-13 22:00:39 +08:00
SELECT geocode_admin1_polygon('Alicante')
2015-11-13 21:59:07 +08:00
`````
2015-11-13 22:22:00 +08:00
* `geocode_admin1_polygon(admin1_name text, country_name text)`
* **Parameters**:
* **Return type:** `polygon`
2015-11-13 21:59:07 +08:00
* **Usage example:**
`````
2015-11-13 22:00:39 +08:00
SELECT geocode_admin1_polygon('Alicante', 'Spain')
2015-11-13 21:59:07 +08:00
`````
2015-11-13 22:22:00 +08:00
#### City geocoder
##### geocode_namedplace_point
2015-11-13 21:59:07 +08:00
* Functions:
2015-11-13 22:22:00 +08:00
* `geocode_namedplace_point(city_name text)`
* **Parameters**:
2015-11-13 21:59:07 +08:00
* **Return type:** `point`
* **Usage example:**
`````
2015-11-13 22:00:39 +08:00
SELECT geocode_namedplace_point('Barcelona')
2015-11-13 21:59:07 +08:00
`````
2015-11-13 22:22:00 +08:00
* `geocode_namedplace_point(city_name text, country_name text)`
* **Parameters**:
* **Return type:** `point`
* **Usage example:**
`````
2015-11-13 22:00:39 +08:00
SELECT geocode_namedplace_point('Barcelona', 'Spain')
2015-11-13 21:59:07 +08:00
`````
2015-11-13 22:22:00 +08:00
* `geocode_namedplace_point(city_name text, admin1_name text, country_name text)`
* **Parameters**:
* **Return type:** `point`
* **Usage example:**
`````
2015-11-13 22:00:39 +08:00
SELECT geocode_namedplace_point('New York', 'New York', 'USA')
2015-11-13 21:59:07 +08:00
`````
2015-11-13 22:22:00 +08:00
#### Postal codes geocoder
##### geocode_postalcode_polygon
2015-11-13 21:59:07 +08:00
* Functions:
2015-11-13 22:22:00 +08:00
* `geocode_postalcode_polygon(code text, country_name text)`
* **Parameters**:
2015-11-13 21:59:07 +08:00
* **Return type:** `polygon`
* **Usage example:**
`````
2015-11-13 22:00:39 +08:00
SELECT geocode_postalcode_polygon('11211', 'USA')
2015-11-13 21:59:07 +08:00
`````
2015-11-13 22:22:00 +08:00
##### geocode_postalcode_point
* Functions:
* `geocode_postalcode_point(code text, country_name text)`
* **Parameters**:
2015-11-13 21:59:07 +08:00
* **Return type:** `point`
* **Usage example:**
`````
2015-11-13 22:00:39 +08:00
SELECT geocode_postalcode_point('11211', 'USA')
2015-11-13 21:59:07 +08:00
`````
2015-11-13 22:22:00 +08:00
#### IP addresses Geocoder
##### geocode_ip_point(ipaddress text)
2015-11-13 21:59:07 +08:00
* Functions:
2015-11-13 22:00:39 +08:00
* `geocode_ip_point(ipaddress text)`
2015-11-13 22:22:00 +08:00
* **Parameters**:
2015-11-13 21:59:07 +08:00
* **Return type:** `point`
* **Usage example:**
`````
2015-11-13 22:00:39 +08:00
SELECT geocode_ip_point('102.23.34.1')
2015-11-13 21:59:07 +08:00
`````
2015-11-13 22:22:00 +08:00