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

applied docs 781 to dataservices-api doc

Browse Source
This commit is contained in:
csobier 2016-05-26 11:00:13 -04:00
parent 587ae051f5
commit 29c719354a
8 changed files with 86 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/API.md
View File

@ -1,6 +1,6 @@
# Data Services API # Data Services API
The CartoDB Data Services API offers a set of location based services that can be used programatically to empower your geospatial applications. The Carto Data Services API offers a set of location based services that can be used programatically to empower your geospatial applications.
## Documentation ## Documentation

14
doc/demographic_functions.md
View File

@ -1,6 +1,6 @@
# Demographic Functions # Demographic Functions
The Demographic Snapshot enables you to collect demographic reports around a point location. For example, you can take the coordinates of a coffee shop and find the average population characteristics, such as total population, educational attainment, housing and income information around that location. You can use raw street addresses by combining the Demographic Snapshot with CartoDB's geocoding features. If you need help creating coordinates from addresses, see the [Geocoding Functions](/cartodb-platform/dataservices-api/geocoding-functions/) documentation. The Demographic Snapshot enables you to collect demographic reports around a point location. For example, you can take the coordinates of a coffee shop and find the average population characteristics, such as total population, educational attainment, housing and income information around that location. You can use raw street addresses by combining the Demographic Snapshot with Carto's geocoding features. If you need help creating coordinates from addresses, see the [Geocoding Functions](/carto-engine/dataservices-api/geocoding-functions/) documentation.
_**Note:** The Demographic Snapshot functions are only available for the United States._ _**Note:** The Demographic Snapshot functions are only available for the United States._
@ -12,7 +12,7 @@ Fields returned include information about income, education, transportation, rac
Name | Description | Example Values Name | Description | Example Values
--- | --- | --- --- | --- | ---
point geometry | A point geometry. You can use the helper function, `CDB_LatLng` to quickly generate one from latitude and longitude | `CDB_LatLng(40.760410,-73.964242)` point geometry | A point geometry. You can use the helper function, `carto_LatLng` to quickly generate one from latitude and longitude | `carto_LatLng(40.760410,-73.964242)`
### Returns ### Returns
@ -40,7 +40,7 @@ obs_getdemographicsnapshot: {
### Examples ### Examples
```bash ```bash
https://{username}.cartodb.com/api/v2/sql?q=SELECT * FROM https://{username}.carto.com/api/v2/sql?q=SELECT * FROM
OBS_GetDemographicSnapshot({{point geometry}}) OBS_GetDemographicSnapshot({{point geometry}})
``` ```
@ -49,15 +49,15 @@ OBS_GetDemographicSnapshot({{point geometry}})
__Get the Demographic Snapshot at Camp David__ __Get the Demographic Snapshot at Camp David__
```bash ```bash
https://{username}.cartodb.com/api/v2/sql?q=SELECT * FROM https://{username}.carto.com/api/v2/sql?q=SELECT * FROM
OBS_GetDemographicSnapshot(CDB_LatLng(39.648333, -77.465)) OBS_GetDemographicSnapshot(carto_LatLng(39.648333, -77.465))
``` ```
__Get the Demographic Snapshot in the Upper West Side__ __Get the Demographic Snapshot in the Upper West Side__
```bash ```bash
https://{username}.cartodb.com/api/v2/sql?q=SELECT * FROM https://{username}.carto.com/api/v2/sql?q=SELECT * FROM
OBS_GetDemographicSnapshot(CDB_LatLng(40.80, -73.960)) OBS_GetDemographicSnapshot(carto_LatLng(40.80, -73.960))
``` ```
## Glossary of Demographic Measures ## Glossary of Demographic Measures

78
doc/geocoding_functions.md
View File

@ -1,25 +1,25 @@
# Geocoding Functions # Geocoding Functions
The [geocoder](https://cartodb.com/data/geocoder-api/) functions allow 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, IP addresses and street addresses. CartoDB provides functions for several different categories of geocoding through the Data Services API. The [geocoder](https://carto.com/data/geocoder-api/) functions allow you to match your data with geometries on your map. This geocoding service can be used programatically to geocode datasets via the Carto SQL API. It is fed from _Open Data_ and it serves geometries for countries, provinces, states, cities, postal codes, IP addresses and street addresses. Carto provides functions for several different categories of geocoding through the Data Services API.
_**This service is subject to quota limitations and extra fees may apply**. View the [Quota Information](http://docs.cartodb.com/cartodb-platform/dataservices-api/quota-information/) section for details and recommendations about to quota consumption._ _**This service is subject to quota limitations and extra fees may apply**. View the [Quota Information](http://docs.carto.com/carto-engine/dataservices-api/quota-information/) section for details and recommendations about to quota consumption._
Here is an example of how to geocode a single country: Here is an example of how to geocode a single country:
```bash ```bash
https://{username}.cartodb.com/api/v2/sql?q=SELECT cdb_geocode_admin0_polygon('USA')&api_key={api_key} https://{username}.carto.com/api/v2/sql?q=SELECT carto_geocode_admin0_polygon('USA')&api_key={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 Data Services 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: In order to geocode an existent Carto dataset, an SQL UPDATE statement must be used to populate the geometry column in the dataset with the results of the Data Services 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 ```bash
https://{username}.cartodb.com/api/v2/sql?q=UPDATE {tablename} SET the_geom = cdb_geocode_admin0_polygon('USA')&api_key={api_key} https://{username}.carto.com/api/v2/sql?q=UPDATE {tablename} SET the_geom = carto_geocode_admin0_polygon('USA')&api_key={api_key}
``` ```
Notice that you can make use of Postgres or PostGIS functions in your Data Services API requests, as the result is a geometry that can be handled by the system. For example, suppose you need to retrieve the centroid of a specific country, you can wrap the resulting geometry from the geocoder functions inside the PostGIS `ST_Centroid` function: Notice that you can make use of Postgres or PostGIS functions in your Data Services API requests, as the result is a geometry that can be handled by the system. For example, suppose you need to retrieve the centroid of a specific country, you can wrap the resulting geometry from the geocoder functions inside the PostGIS `ST_Centroid` function:
```bash ```bash
https://{username}.cartodb.com/api/v2/sql?q=UPDATE {tablename} SET the_geom = ST_Centroid(cdb_geocode_admin0_polygon('USA'))&api_key={api_key} https://{username}.carto.com/api/v2/sql?q=UPDATE {tablename} SET the_geom = ST_Centroid(carto_geocode_admin0_polygon('USA'))&api_key={api_key}
``` ```
@ -29,7 +29,7 @@ The following geocoding functions are available, grouped by categories.
This function geocodes your data into country border geometries. It recognizes the names of the different countries either by different synonyms (such as their English name or their endonym), or by ISO (ISO2 or ISO3) codes. This function geocodes your data into country border geometries. It recognizes the names of the different countries either by different synonyms (such as their English name or their endonym), or by ISO (ISO2 or ISO3) codes.
### cdb_geocode_admin0_polygon(_country_name text_) ### carto_geocode_admin0_polygon(_country_name text_)
Geocodes the text name of a country into a country_name geometry, displayed as polygon data. Geocodes the text name of a country into a country_name geometry, displayed as polygon data.
@ -48,20 +48,20 @@ Geometry (polygon, EPSG 4326) or null
##### Update the geometry of a table to geocode it ##### Update the geometry of a table to geocode it
```bash ```bash
UPDATE {tablename} SET the_geom = cdb_geocode_admin0_polygon({country_column}) UPDATE {tablename} SET the_geom = carto_geocode_admin0_polygon({country_column})
``` ```
##### Insert a geocoded row into a table ##### Insert a geocoded row into a table
```bash ```bash
INSERT INTO {tablename} (the_geom) SELECT cdb_geocode_admin0_polygon('France') INSERT INTO {tablename} (the_geom) SELECT carto_geocode_admin0_polygon('France')
``` ```
## Level-1 Administrative Regions Geocoder ## Level-1 Administrative Regions Geocoder
This function geocodes your data into polygon geometries for [Level 1](https://en.wikipedia.org/wiki/Table_of_administrative_divisions_by_country), or [NUTS-1](https://en.wikipedia.org/wiki/NUTS_1_statistical_regions_of_England), administrative divisions (or units) of countries. For example, a "state" in the United States, "départements" in France, or an autonomous community in Spain. This function geocodes your data into polygon geometries for [Level 1](https://en.wikipedia.org/wiki/Table_of_administrative_divisions_by_country), or [NUTS-1](https://en.wikipedia.org/wiki/NUTS_1_statistical_regions_of_England), administrative divisions (or units) of countries. For example, a "state" in the United States, "départements" in France, or an autonomous community in Spain.
### cdb_geocode_admin1_polygon(_admin1_name text_) ### carto_geocode_admin1_polygon(_admin1_name text_)
Geocodes the name of the province/state into a Level-1 administrative region, displayed as a polygon geometry. Geocodes the name of the province/state into a Level-1 administrative region, displayed as a polygon geometry.
@ -80,17 +80,17 @@ Geometry (polygon, EPSG 4326) or null
##### Update the geometry of a table to geocode it ##### Update the geometry of a table to geocode it
```bash ```bash
UPDATE {tablename} SET the_geom = cdb_geocode_admin1_polygon({province_column}) UPDATE {tablename} SET the_geom = carto_geocode_admin1_polygon({province_column})
``` ```
##### Insert a geocoded row into a table ##### Insert a geocoded row into a table
```bash ```bash
INSERT INTO {tablename} (the_geom) SELECT cdb_geocode_admin1_polygon('Alicante') INSERT INTO {tablename} (the_geom) SELECT carto_geocode_admin1_polygon('Alicante')
``` ```
### cdb_geocode_admin1_polygon(_admin1_name text, country_name text_) ### carto_geocode_admin1_polygon(_admin1_name text, country_name text_)
Geocodes the name of the province/state for a specified country into a Level-1 administrative region, displayed as a polygon geometry. Geocodes the name of the province/state for a specified country into a Level-1 administrative region, displayed as a polygon geometry.
@ -110,12 +110,12 @@ Geometry (polygon, EPSG 4326) or null
##### Update the geometry of a table to geocode it ##### Update the geometry of a table to geocode it
```bash ```bash
UPDATE {tablename} SET the_geom = cdb_geocode_admin1_polygon({province_column}, {country_column}) UPDATE {tablename} SET the_geom = carto_geocode_admin1_polygon({province_column}, {country_column})
``` ```
##### Insert a geocoded row into a table ##### Insert a geocoded row into a table
```bash ```bash
INSERT INTO {tablename} (the_geom) SELECT cdb_geocode_admin1_polygon('Alicante', 'Spain') INSERT INTO {tablename} (the_geom) SELECT carto_geocode_admin1_polygon('Alicante', 'Spain')
``` ```
@ -123,7 +123,7 @@ INSERT INTO {tablename} (the_geom) SELECT cdb_geocode_admin1_polygon('Alicante',
This function geocodes your data into point geometries for names of cities. It is recommended to use geocoding functions that require more defined parameters — this returns more accurate results when several cities have the same name. _If there are duplicate results for a city name, the city name with the highest population will be returned._ This function geocodes your data into point geometries for names of cities. It is recommended to use geocoding functions that require more defined parameters — this returns more accurate results when several cities have the same name. _If there are duplicate results for a city name, the city name with the highest population will be returned._
### cdb_geocode_namedplace_point(_city_name text_) ### carto_geocode_namedplace_point(_city_name text_)
Geocodes the text name of a city into a named place geometry, displayed as point data. Geocodes the text name of a city into a named place geometry, displayed as point data.
@ -144,17 +144,17 @@ Geometry (point, EPSG 4326) or null
##### Update the geometry of a table to geocode it ##### Update the geometry of a table to geocode it
```bash ```bash
UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column}) UPDATE {tablename} SET the_geom = carto_geocode_namedplace_point({city_column})
``` ```
##### Insert a geocoded row into a table ##### Insert a geocoded row into a table
```bash ```bash
INSERT INTO {tablename} (the_geom) SELECT cdb_geocode_namedplace_point('Barcelona') INSERT INTO {tablename} (the_geom) SELECT carto_geocode_namedplace_point('Barcelona')
``` ```
### cdb_geocode_namedplace_point(_city_name text, country_name text_) ### carto_geocode_namedplace_point(_city_name text, country_name text_)
Geocodes the text name of a city for a specified country into a named place point geometry. Geocodes the text name of a city for a specified country into a named place point geometry.
@ -174,17 +174,17 @@ Geometry (point, EPSG 4326) or null
##### Update the geometry of a table to geocode it ##### Update the geometry of a table to geocode it
```bash ```bash
UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column}, 'Spain') UPDATE {tablename} SET the_geom = carto_geocode_namedplace_point({city_column}, 'Spain')
``` ```
##### Insert a geocoded row into a table ##### Insert a geocoded row into a table
```bash ```bash
INSERT INTO {tablename} (the_geom) SELECT cdb_geocode_namedplace_point('Barcelona', 'Spain') INSERT INTO {tablename} (the_geom) SELECT carto_geocode_namedplace_point('Barcelona', 'Spain')
``` ```
### cdb_geocode_namedplace_point(_city_name text, admin1_name text, country_name text_) ### carto_geocode_namedplace_point(_city_name text, admin1_name text, country_name text_)
Geocodes your data into a named place point geometry, containing the text name of a city, for a specified province/state and country. This is recommended for the most accurate geocoding of city data. Geocodes your data into a named place point geometry, containing the text name of a city, for a specified province/state and country. This is recommended for the most accurate geocoding of city data.
#### Arguments #### Arguments
@ -204,22 +204,22 @@ Geometry (point, EPSG 4326) or null
##### Update the geometry of a table to geocode it ##### Update the geometry of a table to geocode it
```bash ```bash
UPDATE {tablename} SET the_geom = cdb_geocode_namedplace_point({city_column}, {province_column}, 'USA') UPDATE {tablename} SET the_geom = carto_geocode_namedplace_point({city_column}, {province_column}, 'USA')
``` ```
##### Insert a geocoded row into a table ##### Insert a geocoded row into a table
```bash ```bash
INSERT INTO {tablename} (the_geom) SELECT cdb_geocode_namedplace_point('New York', 'New York', 'USA') INSERT INTO {tablename} (the_geom) SELECT carto_geocode_namedplace_point('New York', 'New York', 'USA')
``` ```
## Postal Code Geocoder ## Postal Code Geocoder
This function geocodes your data into point, or polygon, geometries for postal codes. The postal code polygon geocoder covers the United States, France, Australia and Canada; a request for a different country will return an empty response. This function geocodes your data into point, or polygon, geometries for postal codes. The postal code polygon geocoder covers the United States, France, Australia and Canada; a request for a different country will return an empty response.
**Note:** For the USA, US Census [Zip Code Tabulation Areas](https://www.census.gov/geo/reference/zctas.html) (ZCTA) are used to reference geocodes for USPS postal codes service areas. See the [FAQs](http://docs.cartodb.com/faqs/datasets-and-data/#why-does-cartodb-use-census-bureau-zctas-and-not-usps-zip-codes-for-postal-codes) about datasets and data for details. **Note:** For the USA, US Census [Zip Code Tabulation Areas](https://www.census.gov/geo/reference/zctas.html) (ZCTA) are used to reference geocodes for USPS postal codes service areas. See the [FAQs](http://docs.carto.com/faqs/datasets-and-data/#why-does-carto-use-census-bureau-zctas-and-not-usps-zip-codes-for-postal-codes) about datasets and data for details.
### cdb_geocode_postalcode_polygon(_postal_code text, country_name text_) ### carto_geocode_postalcode_polygon(_postal_code text, country_name text_)
Goecodes the postal code for a specified country into a **polygon** geometry. Goecodes the postal code for a specified country into a **polygon** geometry.
@ -239,16 +239,16 @@ Geometry (polygon, EPSG 4326) or null
##### Update the geometry of a table to geocode it ##### Update the geometry of a table to geocode it
```bash ```bash
UPDATE {tablename} SET the_geom = cdb_geocode_postalcode_polygon({postal_code_column}, 'USA') UPDATE {tablename} SET the_geom = carto_geocode_postalcode_polygon({postal_code_column}, 'USA')
``` ```
##### Insert a geocoded row into a table ##### Insert a geocoded row into a table
```bash ```bash
INSERT INTO {tablename} (the_geom) SELECT cdb_geocode_postalcode_polygon('11211', 'USA') INSERT INTO {tablename} (the_geom) SELECT carto_geocode_postalcode_polygon('11211', 'USA')
``` ```
### cdb_geocode_postalcode_point(_code text, country_name text_) ### carto_geocode_postalcode_point(_code text, country_name text_)
Goecodes the postal code for a specified country into a **point** geometry. Goecodes the postal code for a specified country into a **point** geometry.
@ -268,13 +268,13 @@ Geometry (point, EPSG 4326) or null
##### Update the geometry of a table to geocode it ##### Update the geometry of a table to geocode it
```bash ```bash
UPDATE {tablename} SET the_geom = cdb_geocode_postalcode_point({postal_code_column}, 'USA') UPDATE {tablename} SET the_geom = carto_geocode_postalcode_point({postal_code_column}, 'USA')
``` ```
##### Insert a geocoded row into a table ##### Insert a geocoded row into a table
```bash ```bash
INSERT INTO {tablename} (the_geom) SELECT cdb_geocode_postalcode_point('11211', 'USA') INSERT INTO {tablename} (the_geom) SELECT carto_geocode_postalcode_point('11211', 'USA')
``` ```
@ -282,7 +282,7 @@ INSERT INTO {tablename} (the_geom) SELECT cdb_geocode_postalcode_point('11211',
This function geocodes your data into point geometries for IP addresses. This is useful if you are analyzing location based data, based on a set of user's IP addresses. This function geocodes your data into point geometries for IP addresses. This is useful if you are analyzing location based data, based on a set of user's IP addresses.
### cdb_geocode_ipaddress_point(_ip_address text_) ### carto_geocode_ipaddress_point(_ip_address text_)
Geocodes a postal code from a specified country into an IP address, displayed as a point geometry. Geocodes a postal code from a specified country into an IP address, displayed as a point geometry.
@ -302,22 +302,22 @@ Geometry (point, EPSG 4326) or null
##### Update the geometry of a table to geocode it ##### Update the geometry of a table to geocode it
```bash ```bash
UPDATE {tablename} SET the_geom = cdb_geocode_ipaddress_point('102.23.34.1') UPDATE {tablename} SET the_geom = carto_geocode_ipaddress_point('102.23.34.1')
``` ```
##### Insert a geocoded row into a table ##### Insert a geocoded row into a table
```bash ```bash
INSERT INTO {tablename} (the_geom) SELECT cdb_geocode_ipaddress_point('102.23.34.1') INSERT INTO {tablename} (the_geom) SELECT carto_geocode_ipaddress_point('102.23.34.1')
``` ```
## Street-Level Geocoder ## Street-Level Geocoder
This function geocodes your data into a point geometry for a street address. CartoDB uses several different service providers for street-level geocoding, depending on your platform. If you access CartoDB on a Google Cloud Platform, [Google Maps geocoding](https://developers.google.com/maps/documentation/geocoding/intro) is applied. All other platform users are provided with [HERE geocoding services](https://developer.here.com/rest-apis/documentation/geocoder/topics/quick-start.html). Additional service providers will be implemented in the future. This function geocodes your data into a point geometry for a street address. Carto uses several different service providers for street-level geocoding, depending on your platform. If you access Carto on a Google Cloud Platform, [Google Maps geocoding](https://developers.google.com/maps/documentation/geocoding/intro) is applied. All other platform users are provided with [HERE geocoding services](https://developer.here.com/rest-apis/documentation/geocoder/topics/quick-start.html). Additional service providers will be implemented in the future.
**This service is subject to quota limitations, and extra fees may apply**. View the [Quota information](http://docs.cartodb.com/cartodb-platform/dataservices-api/quota-information/) for details and recommendations about quota consumption. **This service is subject to quota limitations, and extra fees may apply**. View the [Quota information](http://docs.carto.com/carto-engine/dataservices-api/quota-information/) for details and recommendations about quota consumption.
### cdb_geocode_street_point(_search_text text, [city text], [state text], [country text]_) ### carto_geocode_street_point(_search_text text, [city text], [state text], [country text]_)
Geocodes a complete address into a single street geometry, displayed as point data. Geocodes a complete address into a single street geometry, displayed as point data.
@ -339,11 +339,11 @@ Geometry (point, EPSG 4326) or null
##### Update the geometry of a table to geocode it ##### Update the geometry of a table to geocode it
```bash ```bash
UPDATE {tablename} SET the_geom = cdb_geocode_street_point({street_name_column}) UPDATE {tablename} SET the_geom = carto_geocode_street_point({street_name_column})
``` ```
##### Insert a geocoded row into a table ##### Insert a geocoded row into a table
```bash ```bash
INSERT INTO {tablename} (the_geom) SELECT cdb_geocode_street_point('651 Lombard Street', 'San Francisco', 'California', 'United States') INSERT INTO {tablename} (the_geom) SELECT carto_geocode_street_point('651 Lombard Street', 'San Francisco', 'California', 'United States')
``` ```

24
doc/isoline_functions.md
View File

@ -1,18 +1,18 @@
# Isoline Functions # Isoline Functions
[Isolines](https://cartodb.com/data/isolines/) are contoured lines that display equally calculated levels over a given surface area. This enables you to view polygon dimensions by forward or reverse measurements. Isoline functions are calculated as the intersection of areas from the origin point, measured by distance (isodistance) or time (isochrone). For example, the distance of a road from a sidewalk. Isoline services through CartoDB are available by requesting a single function in the Data Services API. [Isolines](https://carto.com/data/isolines/) are contoured lines that display equally calculated levels over a given surface area. This enables you to view polygon dimensions by forward or reverse measurements. Isoline functions are calculated as the intersection of areas from the origin point, measured by distance (isodistance) or time (isochrone). For example, the distance of a road from a sidewalk. Isoline services through Carto are available by requesting a single function in the Data Services API.
_**This service is subject to quota limitations and extra fees may apply**. View the [Quota Information](http://docs.cartodb.com/cartodb-platform/dataservices-api/quota-information/) section for details and recommendations about to quota consumption._ _**This service is subject to quota limitations and extra fees may apply**. View the [Quota Information](http://docs.carto.com/carto-engine/dataservices-api/quota-information/) section for details and recommendations about to quota consumption._
You can use the isoline functions to retrieve, for example, isochrone lines from a certain location, specifying the mode and the ranges that will define each of the isolines. The following query calculates isolines for areas that are 5, 10 and 15 minutes (300, 600 and 900 seconds, respectively) away from the location by following a path defined by car routing and inserts them into a table. You can use the isoline functions to retrieve, for example, isochrone lines from a certain location, specifying the mode and the ranges that will define each of the isolines. The following query calculates isolines for areas that are 5, 10 and 15 minutes (300, 600 and 900 seconds, respectively) away from the location by following a path defined by car routing and inserts them into a table.
```bash ```bash
https://{username}.cartodb.com/api/v2/sql?q=INSERT INTO {table} (the_geom) SELECT the_geom FROM cdb_isodistance('POINT(-3.70568 40.42028)'::geometry, 'car', ARRAY[300, 600, 900]::integer[])&api_key={api_key} https://{username}.carto.com/api/v2/sql?q=INSERT INTO {table} (the_geom) SELECT the_geom FROM carto_isodistance('POINT(-3.70568 40.42028)'::geometry, 'car', ARRAY[300, 600, 900]::integer[])&api_key={api_key}
``` ```
The following functions provide an isoline generator service, based on time or distance. This service uses the isolines service defined for your account. The default service limits the usage of displayed polygons represented on top of [HERE](https://developer.here.com/coverage-info) maps. The following functions provide an isoline generator service, based on time or distance. This service uses the isolines service defined for your account. The default service limits the usage of displayed polygons represented on top of [HERE](https://developer.here.com/coverage-info) maps.
## cdb_isodistance(_source geometry, mode text, range integer[], [options text[]]_) ## carto_isodistance(_source geometry, mode text, range integer[], [options text[]]_)
Displays a contoured line on a map, connecting geometries to a defined area, measured by an equal range of distance (in meters). Displays a contoured line on a map, connecting geometries to a defined area, measured by an equal range of distance (in meters).
@ -39,29 +39,29 @@ Name | Type | Description
##### Calculate and insert isodistance polygons from a point into another table ##### Calculate and insert isodistance polygons from a point into another table
```bash ```bash
INSERT INTO {table} (the_geom) SELECT the_geom FROM cdb_isodistance('POINT(-3.70568 40.42028)'::geometry, 'walk', ARRAY[300, 600, 900]::integer[]) INSERT INTO {table} (the_geom) SELECT the_geom FROM carto_isodistance('POINT(-3.70568 40.42028)'::geometry, 'walk', ARRAY[300, 600, 900]::integer[])
``` ```
or equivalently: or equivalently:
```bash ```bash
INSERT INTO {table} (the_geom) SELECT (cdb_isodistance('POINT(-3.70568 40.42028)'::geometry, 'walk', ARRAY[300, 600, 900]::integer[])).the_geom INSERT INTO {table} (the_geom) SELECT (carto_isodistance('POINT(-3.70568 40.42028)'::geometry, 'walk', ARRAY[300, 600, 900]::integer[])).the_geom
``` ```
##### Calculate and insert the generated isolines from `points_table` table to another table ##### Calculate and insert the generated isolines from `points_table` table to another table
```bash ```bash
INSERT INTO {table} (the_geom) SELECT (cdb_isodistance(the_geom, 'walk', string_to_array(distance, ',')::integer[])).the_geom FROM {points_table} INSERT INTO {table} (the_geom) SELECT (carto_isodistance(the_geom, 'walk', string_to_array(distance, ',')::integer[])).the_geom FROM {points_table}
``` ```
## cdb_isochrone(_source geometry, mode text, range integer[], [options text[]]_) ## carto_isochrone(_source geometry, mode text, range integer[], [options text[]]_)
Displays a contoured line on a map, connecting geometries to a defined area, measured by an equal range of time (in seconds). Displays a contoured line on a map, connecting geometries to a defined area, measured by an equal range of time (in seconds).
#### Arguments #### Arguments
This function uses the same parameters and information as the `cdb_isodistance` function, with the exception that the range is measured in seconds instead of meters. This function uses the same parameters and information as the `carto_isodistance` function, with the exception that the range is measured in seconds instead of meters.
Name | Type | Description | Accepted values Name | Type | Description | Accepted values
--- | --- | --- | --- --- | --- | --- | ---
@ -75,19 +75,19 @@ Name | Type | Description | Accepted values
##### Calculate and insert isochrone polygons from a point into another table ##### Calculate and insert isochrone polygons from a point into another table
```bash ```bash
INSERT INTO {table} (the_geom) SELECT the_geom FROM cdb_isochrone('POINT(-3.70568 40.42028)'::geometry, 'car', ARRAY[300, 900, 12000]::integer[], ARRAY['mode_traffic=enabled','quality=3']::text[]) INSERT INTO {table} (the_geom) SELECT the_geom FROM carto_isochrone('POINT(-3.70568 40.42028)'::geometry, 'car', ARRAY[300, 900, 12000]::integer[], ARRAY['mode_traffic=enabled','quality=3']::text[])
``` ```
or equivalently: or equivalently:
```bash ```bash
INSERT INTO {table} (the_geom) SELECT (cdb_isochrone('POINT(-3.70568 40.42028)'::geometry, 'car', ARRAY[300, 900, 12000]::integer[], ARRAY['mode_traffic=enabled','quality=3']::text[])).the_geom INSERT INTO {table} (the_geom) SELECT (carto_isochrone('POINT(-3.70568 40.42028)'::geometry, 'car', ARRAY[300, 900, 12000]::integer[], ARRAY['mode_traffic=enabled','quality=3']::text[])).the_geom
``` ```
##### Calculate and insert the generated isolines from `points_table` table into another table ##### Calculate and insert the generated isolines from `points_table` table into another table
```bash ```bash
INSERT INTO {table} (the_geom) SELECT (cdb_isochrone(the_geom, 'walk', string_to_array(time_distance, ',')::integer[])).the_geom FROM {points_table} INSERT INTO {table} (the_geom) SELECT (carto_isochrone(the_geom, 'walk', string_to_array(time_distance, ',')::integer[])).the_geom FROM {points_table}
``` ```
### Optional isoline parameters ### Optional isoline parameters

20
doc/overview.md
View File

@ -1,32 +1,32 @@
# Overview # Overview
By using CartoDB libraries and the SQL API, you can apply location data services to your maps with unique data services functions. These functions are integrated with a number of internal and external services, enabling you to programatically customize subsets of data for your visualizations. These features are useful for geospatial analysis and the results can be saved, and stored, for additional location data service operations. By using Carto libraries and the SQL API, you can apply location data services to your maps with unique data services functions. These functions are integrated with a number of internal and external services, enabling you to programatically customize subsets of data for your visualizations. These features are useful for geospatial analysis and the results can be saved, and stored, for additional location data service operations.
**Note:** Based on your account plan, some of these data services are subject to different [quota limitations](http://docs.cartodb.com/cartodb-platform/dataservices-api/quota-information/#quota-information). **Note:** Based on your account plan, some of these data services are subject to different [quota limitations](http://docs.carto.com/carto-engine/dataservices-api/quota-information/#quota-information).
_The Data Services API is collaborating with [Mapzen](https://mapzen.com/), and several other geospatial service providers, in order to supply the best location data services from within our CartoDB Platform._ _The Data Services API is collaborating with [Mapzen](https://mapzen.com/), and several other geospatial service providers, in order to supply the best location data services from within our Carto Engine._
## Data Services Integration ## Data Services Integration
By using the SQL API to query the Data Services API functions, you can manage specific operations and the corresponding geometries (a `polygon` or a `point`), according to the input information. By using the SQL API to query the Data Services API functions, you can manage specific operations and the corresponding geometries (a `polygon` or a `point`), according to the input information.
The Data Services API decouples the geocoding and isoline services from the CartoDB Editor. The API allows you to geocode data (from single rows, complete datasets, or simple inputs) and to perform trade areas analysis (computing isodistances or isochrones) programatically, through authenticated requests. The Data Services API decouples the geocoding and isoline services from the Carto Editor. The API allows you to geocode data (from single rows, complete datasets, or simple inputs) and to perform trade areas analysis (computing isodistances or isochrones) 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 geometries provided by this API are projected in the projection [WGS 84 SRID 4326](http://spatialreference.org/ref/epsg/wgs-84/).
**Note:** The Data Services API [geocoding functions](http://docs.cartodb.com/cartodb-platform/dataservices-api/geocoding-functions/#geocoding-functions) return different types of geometries (points or polygons) as result of different geocoding processes. The CartoDB Platform does not support multi-geometry layers or datasets, therefore you must confirm that you are using consistent geometry types inside a table, to avoid future conflicts in your map visualization. **Note:** The Data Services API [geocoding functions](http://docs.carto.com/carto-engine/dataservices-api/geocoding-functions/#geocoding-functions) return different types of geometries (points or polygons) as result of different geocoding processes. The Carto Engine does not support multi-geometry layers or datasets, therefore you must confirm that you are using consistent geometry types inside a table, to avoid future conflicts in your map visualization.
### Best Practices ### Best Practices
_Be mindful of the following usage notes when using the Data Services functions with the SQL API:_ _Be mindful of the following usage notes when using the Data Services functions with the SQL API:_
It is discouraged to use the SELECT operation with the Data Services API functions in your map layers, as these type of queries consume quota when rendering tiles for your live map views. It may also result in sync performance issues, due to executing multiple requests to the API each time your map is viewed. See details about [Quota Consumption](http://docs.cartodb.com/cartodb-platform/dataservices-api/quota-information/#quota-consumption). It is discouraged to use the SELECT operation with the Data Services API functions in your map layers, as these type of queries consume quota when rendering tiles for your live map views. It may also result in sync performance issues, due to executing multiple requests to the API each time your map is viewed. See details about [Quota Consumption](http://docs.carto.com/carto-engine/dataservices-api/quota-information/#quota-consumption).
The Data Services API is **recommended** to be used with INSERT or UPDATE operations, for applying location data to your tables. While SELECT (retrieve) is standard for SQL API requests, be mindful of quota consumption and use INSERT (to insert a new record) or UPDATE (to update an existing record), for best practices. The Data Services API is **recommended** to be used with INSERT or UPDATE operations, for applying location data to your tables. While SELECT (retrieve) is standard for SQL API requests, be mindful of quota consumption and use INSERT (to insert a new record) or UPDATE (to update an existing record), for best practices.
## Authentication ## Authentication
All requests performed to the CartoDB Data Services 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/) documentation. All requests performed to the Carto Data Services 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](/carto-engine/sql-api/authentication/) documentation.
## Errors ## Errors
@ -40,10 +40,10 @@ Errors are described in the response of the request. An example is as follows:
} }
``` ```
Since the Data Services 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. Since the Data Services API is used on top of the Carto SQL API, you can refer to the [Making calls to the SQL API](/carto-engine/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. If the requested information is not in the Carto geocoding database, or if Carto 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 Data Services API is subject to the CartoDB SQL API limits, stated in our [Terms of Service](https://cartodb.com/terms/#excessive). Usage of the Data Services API is subject to the Carto SQL API limits, stated in our [Terms of Service](https://carto.com/terms/#excessive).

2
doc/quota_information.md
View File

@ -1,6 +1,6 @@
# Quota Information # Quota Information
**Based on your account plan, some of the Data Services API functions are subject to quota limitations and extra fees may apply.** View our [terms and conditions](https://cartodb.com/terms/), or [contact us](mailto:sales@cartodb.com) for details about which functions require service credits to your account. **Based on your account plan, some of the Data Services API functions are subject to quota limitations and extra fees may apply.** View our [terms and conditions](https://carto.com/terms/), or [contact us](mailto:sales@carto.com) for details about which functions require service credits to your account.
## Quota Consumption ## Quota Consumption

16
doc/routing_functions.md
View File

@ -1,8 +1,8 @@
# Routing Functions # Routing Functions
Routing is the navigation from a defined start location to a defined end location. The calculated results are displayed as turn-by-turn directions on your map, based on the transportation mode that you specified. Routing services through CartoDB are available by using the available functions in the Data Services API. Routing is the navigation from a defined start location to a defined end location. The calculated results are displayed as turn-by-turn directions on your map, based on the transportation mode that you specified. Routing services through Carto are available by using the available functions in the Data Services API.
### cdb_route_point_to_point(_origin geometry(Point), destination geometry(Point), mode text, [options text[], units text]_) ### carto_route_point_to_point(_origin geometry(Point), destination geometry(Point), mode text, [options text[], units text]_)
Returns a route from origin to destination. Returns a route from origin to destination.
@ -30,15 +30,15 @@ Name | Type | Description
##### Insert the values from the calculated route in your table ##### Insert the values from the calculated route in your table
```bash ```bash
INSERT INTO <TABLE> (duration, length, the_geom) SELECT duration, length, shape FROM cdb_route_point_to_point('POINT(-3.70237112 40.41706163)'::geometry,'POINT(-3.69909883 40.41236875)'::geometry, 'car') INSERT INTO <TABLE> (duration, length, the_geom) SELECT duration, length, shape FROM carto_route_point_to_point('POINT(-3.70237112 40.41706163)'::geometry,'POINT(-3.69909883 40.41236875)'::geometry, 'car')
``` ```
##### Update the geometry field with the calculated route shape ##### Update the geometry field with the calculated route shape
```bash ```bash
UPDATE <TABLE> SET the_geom = (SELECT shape FROM cdb_route_point_to_point('POINT(-3.70237112 40.41706163)'::geometry,'POINT(-3.69909883 40.41236875)'::geometry, 'car', ARRAY['mode_type=shortest']::text[])) UPDATE <TABLE> SET the_geom = (SELECT shape FROM carto_route_point_to_point('POINT(-3.70237112 40.41706163)'::geometry,'POINT(-3.69909883 40.41236875)'::geometry, 'car', ARRAY['mode_type=shortest']::text[]))
``` ```
### cdb_route_with_waypoints(_waypoints geometry(Point)[], mode text, [options text[], units text]_) ### carto_route_with_waypoints(_waypoints geometry(Point)[], mode text, [options text[], units text]_)
Returns a route that goes from origin to destination and whose path travels through the defined locations. Returns a route that goes from origin to destination and whose path travels through the defined locations.
@ -60,19 +60,19 @@ Name | Type | Description
`length` | `real` | Length in the defined unit in the `units` field. `kilometers` by default . `length` | `real` | Length in the defined unit in the `units` field. `kilometers` by default .
`the_geom` | `geometry(LineString)` | LineString geometry of the calculated route in the 4326 projection. `the_geom` | `geometry(LineString)` | LineString geometry of the calculated route in the 4326 projection.
*Note*: A request to the function _cdb\_route\_with\_waypoints(waypoints geometry(Point)[], mode text, [options text[], units text])_ with only two points in the geometry array are automatically defined as origin and destination. It is equivalent to performing the following request with these two locations as parameters: _cdb\_route\_point\_to\_point(origin geometry(Point), destination geometry(Point), mode text, [options text[], units text])_. *Note*: A request to the function _carto\_route\_with\_waypoints(waypoints geometry(Point)[], mode text, [options text[], units text])_ with only two points in the geometry array are automatically defined as origin and destination. It is equivalent to performing the following request with these two locations as parameters: _carto\_route\_point\_to\_point(origin geometry(Point), destination geometry(Point), mode text, [options text[], units text])_.
#### Examples #### Examples
##### Insert the values from the calculated route in your table ##### Insert the values from the calculated route in your table
```bash ```bash
INSERT INTO <TABLE> (duration, length, the_geom) SELECT duration, length, shape FROM cdb_route_with_waypoints(Array['POINT(-3.7109 40.4234)'::GEOMETRY, 'POINT(-3.7059 40.4203)'::geometry, 'POINT(-3.7046 40.4180)'::geometry]::geometry[], 'walk') INSERT INTO <TABLE> (duration, length, the_geom) SELECT duration, length, shape FROM carto_route_with_waypoints(Array['POINT(-3.7109 40.4234)'::GEOMETRY, 'POINT(-3.7059 40.4203)'::geometry, 'POINT(-3.7046 40.4180)'::geometry]::geometry[], 'walk')
``` ```
##### Update the geometry field with the calculated route shape ##### Update the geometry field with the calculated route shape
```bash ```bash
UPDATE <TABLE> SET the_geom = (SELECT shape FROM cdb_route_with_waypoints(Array['POINT(-3.7109 40.4234)'::GEOMETRY, 'POINT(-3.7059 40.4203)'::geometry, 'POINT(-3.7046 40.4180)'::geometry]::geometry[], 'car', ARRAY['mode_type=shortest']::text[])) UPDATE <TABLE> SET the_geom = (SELECT shape FROM carto_route_with_waypoints(Array['POINT(-3.7109 40.4234)'::GEOMETRY, 'POINT(-3.7059 40.4203)'::geometry, 'POINT(-3.7046 40.4180)'::geometry]::geometry[], 'car', ARRAY['mode_type=shortest']::text[]))
``` ```

16
doc/segmentation_functions.md
View File

@ -1,6 +1,6 @@
# Segmentation Functions # Segmentation Functions
The Segmentation Snapshot functions enable you to determine the pre-calculated population segment for a location. Segmentation is a method that divides a populations into subclassifications based on common traits. For example, you can take the a store location and determine what classification of population exists around that location. If you need help creating coordinates from addresses, see the [Geocoding Functions](/cartodb-platform/dataservices-api/geocoding-functions/) documentation. The Segmentation Snapshot functions enable you to determine the pre-calculated population segment for a location. Segmentation is a method that divides a populations into subclassifications based on common traits. For example, you can take the a store location and determine what classification of population exists around that location. If you need help creating coordinates from addresses, see the [Geocoding Functions](/carto-engine/dataservices-api/geocoding-functions/) documentation.
_**Note:** The Segmentation Snapshot functions are only available for the United States. Our first release (May 18, 2016) is derived from Census 2010 variables. Our next release will be based on Census 2014 data. For the latest information, see the [Open Segments](https://github.com/CartoDB/open-segments) project repository._ _**Note:** The Segmentation Snapshot functions are only available for the United States. Our first release (May 18, 2016) is derived from Census 2010 variables. Our next release will be based on Census 2014 data. For the latest information, see the [Open Segments](https://github.com/CartoDB/open-segments) project repository._
@ -10,7 +10,7 @@ _**Note:** The Segmentation Snapshot functions are only available for the United
Name | Description | Example Values Name | Description | Example Values
--- | --- | --- --- | --- | ---
point geometry | A point geometry. You can use the helper function, `CDB_LatLng` to quickly generate one from latitude and longitude | `CDB_LatLng(40.760410,-73.964242)` point geometry | A point geometry. You can use the helper function, `carto_LatLng` to quickly generate one from latitude and longitude | `carto_LatLng(40.760410,-73.964242)`
### Returns ### Returns
@ -158,7 +158,7 @@ The possible segments are:
### Examples ### Examples
```bash ```bash
https://{username}.cartodb.com/api/v2/sql?q=SELECT * FROM https://{username}.carto.com/api/v2/sql?q=SELECT * FROM
OBS_GetSegmentSnapshot({{point geometry}}) OBS_GetSegmentSnapshot({{point geometry}})
``` ```
@ -168,14 +168,14 @@ __Get the Segmentation Snapshot around the MGM Grand__
```bash ```bash
https://{username}.cartodb.com/api/v2/sql?q=SELECT * FROM https://{username}.carto.com/api/v2/sql?q=SELECT * FROM
OBS_GetSegmentSnapshot(CDB_LatLng(36.10222, -115.169516)) OBS_GetSegmentSnapshot(carto_LatLng(36.10222, -115.169516))
``` ```
__Get the Segmentation Snapshot at CartoDB's NYC HQ__ __Get the Segmentation Snapshot at Carto's NYC HQ__
```bash ```bash
https://{username}.cartodb.com/api/v2/sql?q=SELECT * FROM https://{username}.carto.com/api/v2/sql?q=SELECT * FROM
OBS_GetSegmentSnapshot(CDB_LatLng(40.704512, -73.936669)) OBS_GetSegmentSnapshot(carto_LatLng(40.704512, -73.936669))
``` ```