cartodb4/dataservices-api
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Applies PR feedback and edits function names

Browse Source
This commit is contained in:
Carla 2015-11-24 15:37:29 +01:00
parent ee28d6768c
commit b93ed72037
1 changed files with 38 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
doc/API.md
View File

@ -1,7 +1,7 @@
## Geocoder API
### Overview
The CartoDB Geocoder API allows you to geocode your data by converting your data into geometries in 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.
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.
@ -9,19 +9,19 @@ If you are using the set of APIs and libraries that CartoDB offers and you are h
Here's an example of how to geocode a single country:
```bash
https://{username}.cartodb.com/api/v2/sql?q=SELECT cdb_geocoder_client.geocode_admin0_polygon('USA')&api_key={Your API key}
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_geocoder_client.geocode_admin0_polygon({country_column})&api_key={Your API key}
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_geocoder_client.geocode_admin0_polygon('USA'))&api_key={Your API key}
https://{username}.cartodb.com/api/v2/sql?q=SELECT ST_Centroid(cdb_geocode_admin0_polygon('USA'))&api_key={Your API key}
```
### General concepts
@ -42,7 +42,7 @@ Errors will be described in the response of the geocoder request. An example is
```json
{
error: [
"function geocode_countries(text) does not exist"
"function cdb_geocode_countries(text) does not exist"
]
}
```
@ -61,9 +61,9 @@ 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.
###### geocode_admin0_polygon
###### cdb_geocode_admin0_polygon
* `geocode_admin0_polygon(country_name text)`
* `cdb_geocode_admin0_polygon(country_name text)`
* **Parameters**:
* Name: `country_name` Type: `text` Description: Name of the country
* **Return type:** Geometry (polygon)
@ -71,20 +71,20 @@ This function provides a country geocoding service. It recognizes the names of t
SELECT
`````
SELECT cdb_geocoder_client.geocode_admin0_polygon('France')
SELECT cdb_geocode_admin0_polygon('France')
`````
UPDATE
`````
UPDATE {tablename} SET {the_geom} = cdb_geocoder_client.geocode_admin0_polygon({country_column})
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.
###### geocode_admin1_polygon
###### cdb_geocode_admin1_polygon
* Functions:
* `geocode_admin1_polygon(admin1_name text)`
* `cdb_geocode_admin1_polygon(admin1_name text)`
* **Parameters**:
* Name: `admin1_name` Type: `text` Description: Name of the province/state
* **Return type:** Geometry (polygon)
@ -92,15 +92,15 @@ The following functions provide a geocoding service for administrative regions o
SELECT
`````
SELECT cdb_geocoder_client.geocode_admin1_polygon('Alicante')
SELECT cdb_geocode_admin1_polygon('Alicante')
`````
UPDATE
`````
UPDATE {tablename} SET the_geom = cdb_geocoder_client.geocode_admin1_polygon({province_column})
UPDATE {tablename} SET the_geom = cdb_geocode_admin1_polygon({province_column})
`````
* `geocode_admin1_polygon(admin1_name text, country_name text)`
* `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
@ -109,20 +109,20 @@ The following functions provide a geocoding service for administrative regions o
SELECT
`````
SELECT cdb_geocoder_client.geocode_admin1_polygon('Alicante', 'Spain')
SELECT cdb_geocode_admin1_polygon('Alicante', 'Spain')
`````
UPDATE
`````
UPDATE {tablename} SET the_geom = cdb_geocoder_client.geocode_admin1_polygon({province_column}, {country_column})
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.
##### geocode_namedplace_point
##### cdb_geocode_namedplace_point
* Functions:
* `geocode_namedplace_point(city_name text)`
* `cdb_geocode_namedplace_point(city_name text)`
* **Parameters**:
* Name: `city_name` Type: `text` Description: Name of the city
* **Return type:** Geometry (point)
@ -130,15 +130,15 @@ The following functions provide a city geocoder service. It is recommended to us
SELECT
`````
SELECT cdb_geocoder_client.geocode_namedplace_point('Barcelona')
SELECT cdb_geocode_namedplace_point('Barcelona')
`````
UPDATE
`````
UPDATE {tablename} SET the_geom = cdb_geocoder_client.geocode_namedplace_point({city_column})
UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column})
`````
* `geocode_namedplace_point(city_name text, country_name text)`
* `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
@ -147,15 +147,15 @@ The following functions provide a city geocoder service. It is recommended to us
SELECT
`````
SELECT cdb_geocoder_client.geocode_namedplace_point('Barcelona', 'Spain')
SELECT cdb_geocode_namedplace_point('Barcelona', 'Spain')
`````
UPDATE
`````
UPDATE {tablename} SET the_geom = cdb_geocoder_client.geocode_namedplace_point({city_column}, 'Spain')
UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column}, 'Spain')
`````
* `geocode_namedplace_point(city_name text, admin1_name text, country_name text)`
* `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
@ -163,71 +163,71 @@ The following functions provide a city geocoder service. It is recommended to us
* **Return type:** Geometry (point)
* **Usage example:**
`````
SELECT cdb_geocoder_client.geocode_namedplace_point('New York', 'New York', 'USA')
SELECT cdb_geocode_namedplace_point('New York', 'New York', 'USA')
`````
UPDATE
`````
UPDATE {tablename} SET the_geom = cdb_geocoder_client.geocode_namedplace_point({city_column}, {province_column}, 'Spain')
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.
##### geocode_postalcode_polygon
##### cdb_geocode_postalcode_polygon
* Functions:
* `geocode_postalcode_polygon(postal_code text, country_name text)`
* `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_geocoder_client.geocode_postalcode_polygon('11211', 'USA')
SELECT cdb_geocode_postalcode_polygon('11211', 'USA')
`````
UPDATE
`````
UPDATE {tablename} SET the_geom = cdb_geocoder_client.geocode_postalcode_polygon({postal_code_column}, 'Spain')
UPDATE {tablename} SET the_geom = cdb_geocode_postalcode_polygon({postal_code_column}, 'Spain')
`````
** Note: For the USA, US Census ZCTAs are considered.
##### geocode_postalcode_point
##### cdb_geocode_postalcode_point
* Functions:
* `geocode_postalcode_point(code text, country_name text)`
* `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_geocoder_client.geocode_postalcode_point('11211', 'USA')
SELECT cdb_geocode_postalcode_point('11211', 'USA')
`````
UPDATE
`````
UPDATE {tablename} SET the_geom = cdb_geocoder_client.geocode_postalcode_point({postal_code_column}, 'United States')
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.
##### geocode_ipaddress_point
##### cdb_geocode_ipaddress_point
* Functions:
* `geocode_ipaddress_point(ip_address text)`
* `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_geocoder_client.geocode_ipaddress_point('102.23.34.1')
SELECT cdb_geocode_ipaddress_point('102.23.34.1')
`````
UPDATE
`````
UPDATE {tablename} SET the_geom = cdb_geocoder_client.geocode_ipaddress_point('102.23.34.1')
UPDATE {tablename} SET the_geom = cdb_geocode_ipaddress_point('102.23.34.1')
`````