.. include:: /global.inc
.. include:: /banner.rst

Quick Start Guide
-----------------

.. warning:: Before doing anything, you'll need an app key (and possibly an API key); see :doc:`v1/authentication` for information on how to obtain it.

.. contents::

HTML Demo Tool
==============

The CFT includes an `HTML API demo tool <https://app.coolfarmtool.org/api/v1/demo/>`_:

.. image:: demo.png
    :width: 600px
    :align: center
    :alt: HTML API demo tool

You can start making calls immediately; paste your "app" key into the input
field and click the "Get API Values" button. The output should be the JSON shown in
the relevant section of the API documentation.

.. todo:: add link to crop calculate format

You may also get a list of the measurement unit names, values and conversion
rates, by clicking the “Get API Values” button with appropriate options
selected under API Endpoint. This can be used to get a list of values
for units of measurement and fertiliser types (and their composition).

You will need to ensure that you have  a valid
“App key” to proceed with any form of API call. Calls which access user
data will also require a valid “API key”, available from the "Help" page.

Interface breakdown
......

  * **App Key**: requested directly from CFA; required for all API calls.

  * **API Key**: found on the "Help" page; look for the "?" at the top-right of
    the page.

  * **Get API Values**: call the adjacent API URL (with the entered data, for
    calls which accept data).

  * **Select Farm Drop-down**: specify which farm to show inputs from the "Farm settings" page, which returns a single farm plus a summary list of all of the assessments associated to that farm.

  * **Select Assessment Drop-down**: specify which assessment to show results
    for, for calls which act on a single assessment.

  * **Select Share Code Drop-down**: specify which share code to show results
    for, for calls which act on a single share code.

  * **Select Share Code Assessment Drop-down**: specify which share code to show results
    for, for calls which act on a list of assessment calculation outputs.

  * **API Endpoint Drop-down**: which API method to call.

  * **Textarea 1**: This is used to enter data to send to the server during a
    calculation API call.

  * **Textarea 2**: This will show the response from the server.

.. note::
    We have recently removed some fields which are considered redundant in version 1.3.0 of the tool.
    These are as follows:

    * **Destination Drop-down**
    * **Port Text Input**
    * **API Version Input**

    We have recently added a new field which are required for Multiple Farms API as of 1.3.0
    This is:

    * **Select Farm Drop-down**

    We have also introduced new UI behaviour on this page, only releveant inputs will be shown
    to the user after selecting an endpoint which requires extra parameters, for example,
    when the :ref:`GET / Farms<Using the farms endpoint>` is selected, the "Select farm" input
    will be revealed to the user. This also applies to other endpoints.


Python
======

The following Python scripts provide examples to run calculations
for crop products and dairy products using the CFT API.


Set-up
......

* Ensure that the `Requests <python-requests.org>`_ library is installed
    (``pip install requests``).

* Open a python shell or file.

* Take one of the scripts below and change the API_KEY.

* Run the script.

Crop assessment
......


    **Example**

    .. literalinclude:: examples/quick_start_crop.py

    **Example response**

    .. literalinclude:: examples/quick_start_crop_response.txt

Dairy assessment
......

    **Example**

    .. literalinclude:: examples/quick_start_dairy.py

    **Example response**

    .. literalinclude:: examples/quick_start_dairy_response.txt