diff --git a/doc/geocoding_functions.md b/doc/geocoding_functions.md index d4dffc2..d7f5dcc 100644 --- a/doc/geocoding_functions.md +++ b/doc/geocoding_functions.md @@ -2,7 +2,7 @@ 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. -_**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.cartodb.com/cartodb-platform/dataservices-api/quota-information/) section for details and recommendations about to quota consumption._ Here is an example of how to geocode a single country: diff --git a/doc/isoline_functions.md b/doc/isoline_functions.md index 3077260..9438e83 100644 --- a/doc/isoline_functions.md +++ b/doc/isoline_functions.md @@ -2,7 +2,7 @@ [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. -_**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.cartodb.com/cartodb-platform/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. polygon({country_column})&api_key={api_key} diff --git a/doc/overview.md b/doc/overview.md index 3c59ef9..c19aff9 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -1,6 +1,6 @@ # Overview -By using CartoDB libraries and the SQL API, you can apply location data services to your maps with select functions. These functions are integrated with a number of internal and external services, enabling you to programatically customize subsets of data for your visualizations. For example, you can transform an address to a geometry with [geocoding functions](http://docs.cartodb.com/cartodb-platform/dataservices-api/geocoding-functions/#geocoding-functions). You can also use [isoline functions](http://docs.cartodb.com/cartodb-platform/dataservices-api/isoline-functions/#isoline-functions) to calculate the travel distance for a defined area. These features are useful for geospatial analysis and the results can be saved, and stored, for additional location data service operations. +By using CartoDB libraries and the SQL API, you can apply location data services to your maps with select 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). @@ -16,6 +16,14 @@ The geometries provided by this API are projected in the projection [WGS 84 SRID **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. +### Best Practices + +_Be mindful of the following usage notes when using the Data Services functions with the SQL API:_ + +If you are using SELECT functions with the Data Services API, these queries consume quota when rendering tiles for your live map views. Additionally, it requires that you need an API Key and can slow down sync performance, 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). + +The Data Services API is **recommended** to be used with INSERT or UPDATE. 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 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. diff --git a/doc/quota_information.md b/doc/quota_information.md index 917af9a..e87dca1 100644 --- a/doc/quota_information.md +++ b/doc/quota_information.md @@ -7,5 +7,8 @@ Quota consumption is calculated based on the number of request made for each function. Be mindful of the following usage recommendations when using the Data Services API functions: * One credit per function call will be consumed. The results are not cached. If the query is applied to a _N_ rows dataset, then _N_ credits are consumed -* Avoid running dynamic queries to these functions in your maps. This can result in credit consumption per map view. **Note:** Queries to the Data Services API, and any of its functions in your maps, may be forbidden in the future +* Avoid running dynamic queries to these functions in your maps. This can result in credit consumption per map view. + + **Note:** Queries to the Data Services API, and any of its functions in your maps, may be forbidden in the future + * It is advised to store results of these queries into your datasets, and refresh them as needed. This ensure more control of quota credits for your account