API Documentation
+++++++++++++++++
   
Use::

    DATA_PROXY_URL?url=...

Parameters
==========

+--------------------+--------------------------------------------+
| Parameter          | Description                                |
+====================+============================================+
| ``url``            | URL of data resource, such as XLS or CSV   |
|                    | file. **This is required**                 |
+--------------------+--------------------------------------------+
| ``type``           | Resource/file type. This overrides         |
|                    | autodetection based on file extension. You |
|                    | should also use this if there is no file   |
|                    | extension in the URL but you know the type |
|                    | of the resource.                           |
+--------------------+--------------------------------------------+
| ``max-results``    | Maximum nuber of results (rows) returned   |
+--------------------+--------------------------------------------+
| ``format``         | Output format. Currently ``json`` and      |
|                    | ``jsonp`` are supported                    |
+--------------------+--------------------------------------------+
| ``audit``          | Set to 1 or ``true`` if you want to get    |
|                    | basic data audit information (see below)   |
+--------------------+--------------------------------------------+

Parameters for XLS files:

+--------------------+--------------------------------------------+
| Parameter          | Description                                |
+====================+============================================+
| ``worksheet``      | Worksheet number                           |
+--------------------+--------------------------------------------+

Parameters for CSV files:

+--------------------+-------------------------------------------------+
| Parameter          | Description                                     |
+====================+=================================================+
| ``encoding``       | Resource file encoding, default is ``utf-8``    |
+--------------------+-------------------------------------------------+
| ``dialect``        | Resource CSV dialect. Accepted values:          |
|                    | ``excel``, ``excel-tab``                        |
+--------------------+-------------------------------------------------+


Response
========

Get whole file as json::

    DATA_PROXY_URL?url=http://democracyfarm.org/f/ckan/foo.csv&format=json
    
result::

    {
       "data" : [
          [ "name","type","amount" ],
          [ "apple","fruit",10 ],
          [ "bananna","fruit",20 ],
          [ "carrot","vegetable",30 ],
          [ "blueberry","fruit", 40 ],
          [ "potato","vegetable",50 ],
          [ "onion","vegetable",60 ],
          [ "garlic","vegetable",70 ],
          [ "orange","vegetable",80 ]
       ],
      "url" : "http://democracyfarm.org/f/ckan/foo.csv",
      "fields": [ "name","type","amount" ]
    }


Get only first 3 rows as json::

    DATA_PROXY_URL?url=http://democracyfarm.org/f/ckan/foo.csv&max-results=3&format=json
    
result::

    {
       "data" : [
          [ "name","type","amount" ],
          [ "apple","fruit",10 ],
          [ "bananna","fruit",20 ],
       ],
       "max-results": 3,
       "url" : "http://democracyfarm.org/f/ckan/foo.csv",
       "fields": [ "name","type","amount" ]
    }

+--------------------+----------------------------------------------------------------------+
| Key                | Value                                                                |
+====================+======================================================================+
| ``data``           | Array of arrays representing rows                                    |
+--------------------+----------------------------------------------------------------------+
| ``fields``         | List of fields which can be used as headers (if available)           |
+--------------------+----------------------------------------------------------------------+
| ``url``            | URL of original resource                                             |
+--------------------+----------------------------------------------------------------------+
| ``length``         | File length, if available                                            |
+--------------------+----------------------------------------------------------------------+
| ``max-results``    | Number of requested results                                          |
+--------------------+----------------------------------------------------------------------+
| ``audit``          | Data audit (if requested by ``audit`` request parameter)             |
+--------------------+----------------------------------------------------------------------+


Data audit keys:

+------------------------+----------------------------------------------------------------------+
| Key                    | Value                                                                |
+========================+======================================================================+
| ``record_count``       | Number of records                                                    |
+------------------------+----------------------------------------------------------------------+
| ``distinct_values``    | Array of distinct values                                             |
+------------------------+----------------------------------------------------------------------+
| ``null_count``         | Count of Null values (not present)                                   |
+------------------------+----------------------------------------------------------------------+
| ``null_record_ratio``  | Ratio of null values to number of records                            |
+------------------------+----------------------------------------------------------------------+
| ``empty_string_count`` | Count of empty strings                                               |
+------------------------+----------------------------------------------------------------------+



Errors
======

+----------------------------------------+----------------------------------------------------+
| Error                                  | Resolution                                         |
+========================================+====================================================+
| Unknown reply format                   | Specify supported reply ``format`` (json, jsonp)   |
+----------------------------------------+----------------------------------------------------+
| No url= option found                   | Provide obligatory ``url`` parameter               |
+----------------------------------------+----------------------------------------------------+
| Could not determine the file type      | URL file/resource has no known file extension,     |
|                                        | provide file type in ``type`` parameter:           |
|                                        | ``type=csv``                                       |
+----------------------------------------+----------------------------------------------------+
| Resource type not supported            | There is no tranformation module available for     |
|                                        | given resource/file type. Please refer to the list |
|                                        | of supported resource types.                       |
+----------------------------------------+----------------------------------------------------+
| Only http is allowed                   | Only HTTP URL scheme is currently supported. Make  |
|                                        | sure that you are accessing HTTP only or try to    |
|                                        | find HTTP alternative for the resource.            |
+----------------------------------------+----------------------------------------------------+
| Could not fetch file                   | It was not possible to access resource at given URL|
|                                        | Check the URL or resource hosting server.          |
+----------------------------------------+----------------------------------------------------+
| The requested file is too big to proxy | Proxy handles files only within certain size limit.|
|                                        | Use alternative smaller resource if possible.      |
+----------------------------------------+----------------------------------------------------+
| Data transformation error              | An error occured during transformation of resource |
|                                        | to structured data. Please refer to the additional |
|                                        | message to learn what went wrong.                  |
+----------------------------------------+----------------------------------------------------+