Command line interface
======================

The ``omdpb`` package comes with a command line tool called **openmeteodata**.
Once the package is installed, from a terminal you can type:

.. code-block:: bash

   openmeteodata -h

This prints a documentation of the command line arguments and their usage.

Positional arguments
--------------------

``openmeteodata`` takes exactly one positional argument which is the type of data 
to request. Valid choices are ``stations`` (station metadata), ``sensors`` (sensor metadata)
and ``timeseries`` (sensor timeseries).

* ``stations``: retrieves a list of all available meteorological stations.
* ``sensors``: retrieves a list of all available sensors of a specific station.
* ``timeseries``: retrieves a time series of one or more sensors of a specific station.

Optional arguments
------------------

The optional arguments are grouped into query and output options:

* Query options
	- ``-stc``, ``--station_code``: The station identifier, column **SCODE** in ``openmeteodata stations`` output.
	- ``-snc``, ``--sensor_code``: The sensor identifier(s), column **TYPE** in ``openmeteodata sensors`` output.
	- ``-df``, ``--date_from``: The starting date when querying a time series with ``openmeteodata timeseries``.
	- ``-dt``, ``--date_to``: The ending date when querying a time series with ``openmeteodata timeseries``.

* Output options
	- ``-s``, ``--save``: save the output to file
	- ``-f``, ``--format``: if ``-s`` is set, ``-f`` specifies the output file format, valid choices are *csv* or *json*.
	- ``-p``, ``--path``: output file path
	- ``-fn``, ``--file_name``: output file name

Examples
--------

* To get started, type:

  .. code-block:: bash
   
     openmeteodata stations

  This will print a list of the available stations including name, station code,  position, etc. The 
  station code (column SCODE) is needed to retrieve data and metadata from the sensors.

* To retrieve all sensors, e.g. of the station in Bolzano, together with the last measured values use:

  .. code-block:: bash
  
     openmeteodata sensors -stc 83200MS
  
  where ``83200MS`` is the station code (SCODE) of Bolzano. To retrieve only some sensors, you could use:
  
  .. code-block:: bash
  
	 openmeteodata sensors -stc 83200MS -snc LT N WR
	
* To retrieve a time series of the last 24 hours of all sensors at the station in Bolzano use:

  .. code-block:: bash
  
	 openmeteodata timeseries -stc 83200MS
  
  This will ask you to specify the desired sensors, simply press <ENTER> to choose all. To retrieve
  only a specific set of sensors, use:
  
  .. code-block:: bash
  
	 openmeteodata timeseries -stc 83200MS -snc LT WR WG LF

  To retrieve a time series of the last 24h before ``--date_to`` use:
  
  .. code-block:: bash
  
	 openmeteodata timeseries -stc 83200MS -dt 20180101

  Analogously, to retrieve a time series of the last 24h after ``--date_from`` use:
  
  .. code-block:: bash
  
	 openmeteodata timeseries -stc 83200MS -df 20180101

  Finally, to retrieve a time series from ``date_from`` to ``date_to`` use:
  
  .. code-block:: bash
  
	 openmeteodata timeseries -stc 83200MS -df 20180101 - dt 20180131
	
  To save the output to a .csv file with name "Test_Documentation.csv" use:
  
  .. code-block:: bash
  
	 openmeteodata timeseries -stc 83200MS -df 20180101 - dt 20180131 -s -fn Test_Documentation
	
  For .json ouput use the ``-f`` argument:
  
  .. code-block:: bash
  
	 openmeteodata timeseries -stc 83200MS -df 20180101 - dt 20180131 -s -fn Test_Documentation -f json

  If you don't specify the file name, the ``station_code`` will take it's place:
  
  .. code-block:: bash
  
	 openmeteodata timeseries -stc 83200MS -df 20180101 - dt 20180131 -s 
	 
  This should create the file *home/<user>/documents/83200MS.csv*, where **home/<user>/documents/** is the default path
  and can be changed by setting the ``-p`` argument:
  
  .. code-block:: bash
  
	 openmeteodata timeseries -stc 83200MS -df 20180101 - dt 20180131 -s -p <your-file-path> -f json
   
  This should create the file *<your-file-path>/83200MS.json*.