.. _timeseries-profile-byID-endpoint:

TimeSeries — GET /timeseries/profile/{location-id}/{parameter-id}
===================================================================


What it does
------------
Retrieves a specific time series profile for a given location and parameter.

A "profile" stores multiple values for each point in time. Think of it as a combination of time series data
and paired data. It’s called a “profile” because it’s often used for things like temperature profiles in lakes over time.

In profile data, there is:

- An independent variable (e.g., Depth)
- Dependent variables (e.g., Temperature at those depths over time)

The independent variable describes the dependent variables and is NOT tied to time.  For example, in a lake temperature
profile, depths are the independent variable, and temperatures at those depths are the dependent variables.

The endpoint path must include the independent variable name, followed by a dash "-", and then the dependent variable
name. For example: `/Depth-Temperature/`.

Important Rules:

- The number of independent variables must stay consistent across the entire dataset. For example, if you have 10 depth
  readings, you must keep 10 depth readings for the entire dataset (missing values can be marked as such).
- You must include an independent variable set, even if it's not used. For example, if you store multiple time series
  values, you still need an independent variable array, (it can contain zeros if unused).

Profile data can include quality indicators and notes, similar to other time series data. It can use regular or
irregular intervals, with minute granularity (default) or second granularity.

When to use
-----------
- You wish to retrieve a specific time series profile and already know the location and parameter.


.. csv-table:: GET /timeseries/profile/{location-id}/{parameter-id} - Endpoint Parameters
    :header: "Parameter", "Description", "Required", "When to Use"
    :widths: 30, 40, 20, 65

    location-id,":ref:`def-location-id`","Yes", ":ref:`when_location_id`"
    parameter-id,":ref:`def-parameter-id`","Yes", ":ref:`when_parameter_id`"
    office,":ref:`def-office`","", ":ref:`when_office`"

Examples
--------

1. | The user wants to retrieve the temperature profile at various depths:
   | (**parameter-id**) :code:`Depth-Temperature`
   |
   | for the RIVER-STATION1 location:
   | (**location-id**) :code:`RIVER-STATION1`
   |
   | but is unsure of which office to use. Query includes required path parameters, `location-id` and `parameter-id`.

   .. code-block:: bash

       GET /timeseries/profile/[location-id]/[parameter-id]

   .. code-block:: bash

       GET /timeseries/profile/RIVER-STATION1/Depth-Temperature

2. The user reviews the results from the previous example query and decides to to narrow the search to the `HQ` office.
   Query remains the same:

   | (**parameter-id**) :code:`Depth-Temperature`
   |
   | (**location-id**) :code:`RIVER-STATION1`
   |
   | but adds the optional query parameter, `office`:
   | (**office**) :code:`HQ`

   .. code-block:: urlencoded

       GET /timeseries/profile/[location-id]/[parameter-id]?office=[office]

   .. code-block:: urlencoded

       GET /timeseries/profile/LOC123/Depth-Temperature?office=HQ


See the consolidated API documentation: :doc:`/api-references`.

.. include:: /_includes/feedback_button.rst