# Units

API Deprecation Notice
The legacy API (v0) **has been deprecated**. While it will continue to receive and process incoming data, creating new data sources compatible with this version **is no longer supported**. No further updates or improvements are planned, and no official sunset date has been set at this time.

A [new API (v2)](/docs/api/overview) is available, offering enhanced capabilities including raw data ingestion and full integration with the [datasets](https://help.databox.com/understanding-datasets) functionality.

You can attach **units** (such as currencies or measurement units) to metric values.
This allows you to store different types of values under the same metric.

For example, a metric like *Closed Won Deals* can store both EUR and USD values by attaching the appropriate unit to each entry.

## Units vs. dimensions

- **Dimensions** provide extra context about *where* or *how* a value was generated
(e.g., which store produced sales of 8,300).
- **Units** describe *what the value measures* (e.g., 8,300 **USD** vs. 8,300 **EUR**).


Units are most commonly used for **currencies**, but can also represent measurements like *kg*, *hours*, or *items*.

## How to use units

When pushing data to Databox, include the `unit` property along with the metric key and value.
Each data point can have its own unit, allowing you to mix multiple currencies or measurement types in the same metric.

## Examples

cURL
```bash
curl https://push.databox.com/data \
-u <your_token>: \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/vnd.databox.v2+json' \
-d '[
      {
        "key": "sales",
        "value": 8300,
        "unit": "USD"
      },
      {
        "key": "sales",
        "value": 4000,
        "unit": "EUR"
      }
  ]'
```

C#
```csharp
using System.Diagnostics;
using Databox.Api;
using Databox.Client;
using Databox.Model;

namespace Example
{
  public class Example
  {
    public static async Task Main(string[] args)
    {

      Configuration config = new Configuration();
      config.BasePath = "https://push.databox.com";
      config.Username = "<your_token>";
      config.DefaultHeaders.Add("Accept", "application/vnd.databox.v2+json");

      HttpClient httpClient = new HttpClient();
      HttpClientHandler httpClientHandler = new HttpClientHandler();
      var apiInstance = new DefaultApi(httpClient, config, httpClientHandler);
      var dataPostRequest = new List<PushData>() {
        new PushData()
        {
            Key = "sales",
            Value = 8300,
            Unit = "USD"
        },
        new PushData()
        {
            Key = "sales",
            Value = 4000,
            Unit = "EUR"
        }
        
      };

      try
      {
        var response = await apiInstance.DataPostWithHttpInfoAsync(dataPostRequest);
        Console.WriteLine(response.Data.ToString());
      }
      catch (ApiException e)
      {
        Console.WriteLine("Exception when calling DefaultApi.DataPostWithHttpInfo: " + e.Message);
        Console.WriteLine("Status Code: " + e.ErrorCode);
        Console.WriteLine(e.StackTrace);
      }
    }
  }
}
```

Go
```go
package main

import (
  "context"
  "fmt"
  "os"
  "time"

  databox "github.com/databox/databox-go/databox"
)

const t = "<your_token>" // Your Databox token

func main() {

  // Create a context with basic auth
  auth := context.WithValue(context.Background(), databox.ContextBasicAuth, databox.BasicAuth{UserName: t})

  // Create a configuration
  cfg := databox.NewConfiguration()
  cfg.DefaultHeader["Content-Type"] = "application/json"
  cfg.DefaultHeader["Accept"] = "application/vnd.databox.v2+json"

  // Create an API client
  api := databox.NewAPIClient(cfg)


  data1 := databox.NewPushData()
  data1.SetKey("sales")
  data1.SetValue(8300)
  data1.SetUnit("USD")


  data2 := databox.NewPushData()
  data2.SetKey("sales")
  data2.SetValue(4000)
  data2.SetUnit("EUR")


  // Push the data (send both PushData objects)
  r, err := api.DefaultAPI.DataPost(auth).PushData([]databox.PushData{*data1, *data2}).Execute()
  if err != nil {
    fmt.Fprintf(os.Stderr, "Error when calling `DefaultAPI.DataPost``: %v\n", err)
  }

  fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
}
```

Java
```java
import org.databox.ApiClient;
import org.databox.ApiException;
import org.databox.Configuration;
import org.databox.api.DefaultApi;
import org.databox.auth.HttpBasicAuth;
import org.openapitools.client.model.PushData;

import java.util.List;

public class PushDataExample {
    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("https://push.databox.com");
        defaultClient.addDefaultHeader("Accept", "application/vnd.databox.v2+json");

        HttpBasicAuth basicAuth = (HttpBasicAuth) defaultClient.getAuthentication("basicAuth");
        basicAuth.setUsername("<your_token>");

        DefaultApi apiInstance = new DefaultApi(defaultClient);

        try {
            apiInstance.dataPost(List.of(
                new PushData()
                    .key("sales")
                    .value(8300)
                    .unit("USD"),
                
                new PushData()
                    .key("sales")
                    .value(4000)
                    .unit("EUR"),
            ));
        } catch (ApiException e) {
            e.printStackTrace();
        }
    }
}
```

JavaScript
```javascript
import {
  ApiResponse,
  Configuration,
  DataPostRequest,
  DefaultApi,
} from "databox";

const config: Configuration = new Configuration({
  basePath: "https://push.databox.com",
  username: "<your_token>",
  headers: {
    Accept: "application/vnd.databox.v2+json",
  },
});

const dataPostRequest: DataPostRequest = {
  pushData: [
    {
      key: "sales",
      value: 8300,
      unit: "USD",
    },
    {
      key: "sales",
      value: 4000,
      unit: "EUR",
    },
  ],
};

const api = new DefaultApi(config);

try {
  api
    .dataPostRaw(dataPostRequest)
    .then((response: ApiResponse<void>) => response.raw.json())
    .then((responseBody) => {
      console.log("Response data", responseBody);
    });
} catch (error) {
  console.log("Error: ", error);
}
```

PHP
```php
<?php

require_once __DIR__ . '/../../../vendor/autoload.php';

use Databox\Api\DefaultApi;
use Databox\ApiException;
use Databox\Configuration;
use Databox\Model\PushData as DataboxPushData;
use GuzzleHttp\Client;

execute();

function execute()
{
    // Configure HTTP basic authorization: basicAuth
    $config = Configuration::getDefaultConfiguration()
        ->setHost('https://push.databox.com')
        ->setUsername('<your_token>');

    $headers = [
        'Content-Type' => 'application/json',
        'Accept'       => 'application/vnd.databox.v2+json'
    ];

    $apiInstance = new DefaultApi(
        new Client(['headers' => $headers]),
        $config
    );

    try {
        $apiInstance->dataPost([
            (new DataboxPushData())
                ->setKey('sales')
                ->setValue(8300)
                ->setUnit('USD'),
            
            (new DataboxPushData())
                ->setKey('sales')
                ->setValue(4000)
                ->setUnit('EUR')
        ]);

        echo "Successfully pushed data to Databox";
    } catch (ApiException $e) {
        echo 'Exception when calling DefaultApi->dataPost: ' . $e->getMessage() . PHP_EOL . $e->getResponseBody() . PHP_EOL;
    }
}
```

Python
```python
# Configuration setup for the Databox API client
# The API token is used as the username for authentication
# It's recommended to store your API token securely, e.g., in an environment variable
configuration = databox.Configuration(
    host="https://push.databox.com",
    username="<your_token>",
    password=""
)

# It's crucial to specify the correct Accept header for the API request
with databox.ApiClient(configuration, "Accept", "application/vnd.databox.v2+json", ) as api_client:
    api_instance = databox.DefaultApi(api_client)

    # Define the data to be pushed to the Databox API# Prepare the data you want to push to Databox
    push_data = [
        {
            "key": "sales",
            "value": 8300,
            "unit": "USD"
        },
        {
            "key": "sales",
            "value": 4000,
            "unit": "EUR"
        }
    ]

    try:
        api_instance.data_post(push_data=push_data)
    except ApiException as e:
        # Handle exceptions that occur during the API call, such as invalid data or authentication issues
        pprint("API Exception occurred: %s\n" % e)
    except Exception as e:
        # Handle any other unexpected exceptions
        pprint("An unexpected error occurred: %s\n" % e)
```