# Using a data file data source

You can use raw data stored in a file using the `data_file` datasource. 

It works this way : 

1. You upload a data file in the platform using the `data_file` API
2. You reference this file in the dashboard as a dataset
3. This source can then be transformed and display like all other data sources.

## Upload your raw data in the platform

Use the data\_file API to upload any JSON file containing your raw data. Its structure is not fixed. 

{% code title="Sample JSON" %}

```json5
  {
      "id": "1",
      "name": "Demographics",
      "other_metadata_as_you_wish": "SEGMENT",
      "genders": [
          {
            "key": "male",
            "value": 358
          },
          {
            "key": "female",
            "value": 66
          }
      ],
      "ages": [
        {
          "key": "18-24",
          "count": 277
        },
        {
          "key": "45-54",
          "count": 8
        },
        {
          "key": "65+",
          "count": 9
        },
        {
          "key": "25-34",
          "count": 12
        },
        {
          "key": "35-44",
          "count": 9
        },
        {
          "key": "55-64",
          "count": 3
        }
    ],
    "total": 666
}
```

{% endcode %}

There are two types of datasets that you can use : 

### Key / value dataset

A default key / value dataset is an array of key / value objects.

```json5
{
    "key_value_dataset": [
        {
            "key": "Dimension 1",
            "value": 666
        }
        ...
        {
            "key": "Dimension X",
            "value": 999
        }
    ]
}
```

{% hint style="info" %}
The `value` property could be named differently, such as `count` or `value-1` by using the `series_title` property of the data source.
{% endhint %}

### Number dataset

```json5
{
    ...
    "total": 666
}
```

## Reference this file in your charts

The whole structure of the dashboard is exactly the same as with other data sources. 

* For more information on datasets and datasources, see [Datasets and data sources](https://developer.mediarithmics.io/dashboards/datasets-and-data-sources/..#dataset-json-declaration). 
* For a quick start on how to upload a dashboard, see [Quickstart](https://developer.mediarithmics.io/dashboards/quickstart).

The data source declaration is : 

```json5
{
      "type": "data_file",
      // URI of the JSON data file containing data
      // Format "mics://data_file/tenants/1426/dashboard-1.json"
      "uri": String,
      // Path of the property in the JSON that should be used as dataset
      // This allows you to have multiple datasets in the same JSON file
      // Should use the JSONPath syntax. See https://jsonpath.com/
      // For example, "$[0].components[1].component.data"
      "JSON_path": String,
      // Optional. Title of the series for tooltips and legends
      "series_title": String
}
```

Here is an example with the JSON file we used previously 

```json5
{
    "sections": [
        {
            "title": "Section",
            "cards": [
                {
                    "x": 0,
                    "charts": [
                        {
                            "title": "Gender",
                            "type": "Bars",
                            "dataset": {
                                "type": "data_file",
                                "uri": "mics://data_file/tenants/XXX/dashboard-1.json",
                                "JSON_path": "$.genders"
                            }
                        }
                    ],
                    "y": 0,
                    "h": 3,
                    "layout": "vertical",
                    "w": 4
                },
                {
                    "x": 4,
                    "charts": [
                        {
                            "options": {
                                "legend": {
                                    "enabled": true,
                                    "position": "right"
                                }
                            },
                            "dataset": {
                                "type": "data_file",
                                "uri": "mics://data_file/tenants/XXX/dashboard-1.json",
                                "JSON_path": "$.ages",
                                "series_title": "count"
                            },
                            "title": "Age range",
                            "type": "Pie"
                        }
                    ],
                    "y": 0,
                    "h": 3,
                    "layout": "vertical",
                    "w": 5
                },
                {
                    "x": 9,
                    "charts": [
                        {
                            "title": "Totals",
                            "type": "Metric",
                            "dataset": {
                                "type": "data_file",
                                "uri": "mics://data_file/tenants/XXX/dashboard-1.json",
                                "JSON_path": "$.total"
                            }
                        }
                    ],
                    "y": 0,
                    "h": 3,
                    "layout": "vertical",
                    "w": 3
                }
            ]
        }
    ]
}
```

You can use a `{SEGMENT_ID}` token in `uri` and/or `JSON_path` properties. It will be replaced by the current segment if the dashboard is loaded on a segment's page. If the dashboard is loaded at any other scope, the token will not be replaced.