Data Services API v0.0.2

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, or contact us for details about which functions require service credits to your account.

Quota Consumption

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

• 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

Quota Information Functions

There are several SQL functions that you can run to obtain quota information about your services.

cdb_service_quota_info()

Returns information about per-service quotas (available and used) for the account.

Returns

This function returns a set of service quota information records, one per service.

Service Types:

• 'isolines' Isoline/Isochrones (isochrone/isodistance lines) service
• 'hires_geocoder' Street level geocoding
• 'routing' Routing functions

Notes

Users who have soft-quota activated never run out of quota, but they may incur extra expenses when the regular quota is exceeded.

A zero value of monthly_quota indicates that the service has not been activated for the user.

Example

1
SELECT * FROM cdb_service_quota_info();

Result:

1
2
3
4
5
6
7
    service     | monthly_quota | used_quota | soft_limit |     provider
----------------+---------------+------------+------------+------------------
 isolines       |           100 |          0 | f          | tomtom
 hires_geocoder |           100 |          0 | f          | tomtom
 routing        |            50 |          0 | f          | tomtom
(4 rows)

All quotas are hard-limited (no soft limits), and no quota has been used in the present period.

cdb_enough_quota(service text ,input_size numeric)

This function is useful to check if enough quota is available for completing a job.

This is specifically relevant if a number of service calls are to be performed inside a transaction. If any of the calls fails (due to exceeded quota), the transaction will be rolled back; resulting in partial quota consumption, but no saved results from the services consumed.

Tip: If you are requesting repeating quota-consuming functions (e.g. to geocode a whole table), it is extremely important to check if enough quota is available to complete the job before applying this function.

Note that some services consume more than one credit per row/call. For example, isolines (with more than one range/track) consume (N rows x M ranges) credits; indicating that the input size should be N x M.

Arguments

Returns

The result is a boolean value. A true value ('t') indicates that the available quota for the service is enough for the input size requested. A false value ('f') indicates insufficient quota.

Example

Suppose you want to geocode a whole table. In order to check that you have enough quota, and avoid a “quota exhausted” exception, first find out how many records you need to geocode:

1
SELECT COUNT(*) FROM {tablename} WHERE {street_name_column} IS NOT NULL;

Result: A sample result of 10000 records:

1
2
3
4
 count
-------
  10000
(1 row)

The result shows how much quota is needed to complete this job. In this case, each call to cdb_geocode_street_point consumes one quota credit. This indicates that we need one credit per row to geocode the whole table.

1
SELECT cdb_enough_quota('hires_geocoder', {number_of_records});

The result is similar to the following:

1
2
3
 cdb_enough_quota
------------------
 t

If the result of this query is true ('t'), you can safely proceed. If a false value ('f') is returned, you should avoid processing any more requests that consume quota. Apply the cdb_service_quota_info function to get more information about your services.

Note: Remember to apply any filtering conditions that you used to count the records (in this case, {street_name_column} IS NOT NULL):

1
2
UPDATE {tablename} SET the_geom = cdb_geocode_street_point({street_name_column})
  WHERE {street_name_column} IS NOT NULL;