====== readAPI() ======

''array **readAPI**(string //API ID//, string //request//, [string //API Key//])''

APIs (standardized interfaces, Application Programming Interface) allow third-party services to be incorporated into the developer's own software or questionnaire. The function ''readAPI()'' accesses these services directly within the questionnaire.

  * //API ID//\\ The ID of the service to be used. Currently, SoSci Survey supports the following APIs:
    * //google.maps.v3// -- [[https://developers.google.com/maps/documentation/javascript/reference|Google Maps v3]]
    * //cloudmade.geocoding.v2// -- [[http://developers.cloudmade.com/projects/show/geocoding-http-api|Cloudmade: Geocoding/Geosearch]]
    * **Note:** Further APIs can be added within more specific research projects -- please send all requests directly to [[info@soscisurvey.de|SoSci Survey]].
  * //request//\\ the request to the API, coded in GET format
  * //API Key//\\ If the use of the API requires a key to be specifed, this is entered as the third parameter. Normally a key is used to calculate the bill for API services.

The function translates the answer of the API directly into an array, which can be set up relatively easily in PHP. Use the function ''debug()'' to display the content of the answer.

===== Example =====

<code php>
// request to Google Maps (search for a street using coordinates)
$v = readAPI('google.maps.v3','latlng=40.714224,-73.961452&sensor=false');
debug($v);
// output of street found
html('<p>Straße: '.$v['results'][0]['address_components'][1]['long_name'].'</p>');
</code>

<code php>
// request to Cloudmade
$v = readAPI('cloudmade.geocoding.v2','around=52.4870,13.4248&distance=closest&object_type=address&return_location=true','API-KEY');
debug($v);
</code>