# Build your own site with Observable

{% hint style="success" %}
This guide outlines an example [static site](https://labs.redivis.com/observable/) hosted by the Redivis team. Follow along at the [Observable on Redivis Github repository](https://github.com/redivis/observable) to see all the details and build your own!
{% endhint %}

## Overview

It's easy to use of Redivis data anywhere on the web, either by [interfacing programmatically](https://docs.redivis.com/reference/tables/exporting-tables/programmatic) via our client libraries, [visualizing](https://docs.redivis.com/reference/tables/exporting-tables/google-data-studio) via one of our export integrations, or [embedding a table](https://docs.redivis.com/reference/tables/exporting-tables/embedding-tables) directly in another webpage.

To present Redivis data in a fully customizable way, you may want to build your own dashboard-style site. The following example shows a static site built with [Observable Framework](https://observablehq.com/framework/getting-started), deployed via [Github Pages](https://docs.github.com/en/pages/quickstart), that connects to Redivis data using our client libraries.

{% hint style="info" %}
To try a lighter-weight "dashboard" for analyzing and visualizing your data, you can use integrated [Redivis notebooks](https://docs.redivis.com/guides/analyze-data-in-a-workflow/work-with-data-in-notebooks). With notebooks, you can work directly in your Redivis workflow alongside relevant source data, leverage a breadth of techniques and libraries available in the Python, R, Stata or SAS ecosystems, and easily maintain a central asset to annotate, collaborate, and share.
{% endhint %}

## 1. Identify your Redivis data

Identify the data sources on Redivis that will provide the content to build your site. You may be interested in presenting facets of a [dataset](https://docs.redivis.com/guides/discover-and-access-data/discover-datasets) already hosted on Redivis, highlighting tables you [uploaded](https://docs.redivis.com/guides/create-and-manage-datasets/upload-tabular-data-as-tables) yourself, or showing outputs generated in one of your [workflows](https://docs.redivis.com/guides/analyze-data-in-a-workflow).\
\
In our example, we'll use weather station locations contained in the [GHCN Daily Weather dataset](https://redivis.com/datasets/7br5-41440fjzk), and outputs from a [public Redivis workflow](https://redivis.com/projects/x7kh-5pvd4mbf1/tables/287477) that uses the same source data, to visualize locations and aggregate precipitation measurements from around the world.

To reference a Redivis table, choose the "Export table" option and navigate to the "Programmatic" tab (e.g., the [GHCN Daily Weather "Stations" table](https://redivis.com/datasets/7br5-41440fjzk/tables/g2q3-fs847tjwe?exportTable=g2q3-fs847tjwe\&exportDestination=programmatic)), and see the code snippet for unique identifiers for the owner, dataset/workflow, and table. More details about [referencing Redivis resources](https://app.gitbook.com/s/GCgH8jTSmY8Vgwceiri5/referencing-resources) here.

## 2. Build your Observable project

With chosen data content in mind, the next step is to choose a set of tools to build our custom dashboard and deploy it to the web. Of the numerous choices, [Observable Framework](https://observablehq.com/framework/) provides an approachable option with support for working with data in many programming languages (not just javascript), powerful visualization libraries built in, and excellent documentation.\
\
To start with a copy of our example dashboard, you can clone our public [Github repo](https://github.com/redivis/observable) and follow the README.md instructions to develop a similar site in a local environment. To create a brand new project, and to reference additional details and development strategies, see the Observable [Getting started](https://observablehq.com/framework/getting-started) guide. 

## 3. Load data with a client library of choice

You'll need to generate a Redivis API access token with appropriate permissions. See [Authorization](https://app.gitbook.com/s/GCgH8jTSmY8Vgwceiri5/rest-api/authorization) in our API documentation to create your own token to read data from Redivis.

 To successfully authorize data fetching functionality in your development environment, be sure to export a `REDIVIS_API_TOKEN` variable to your path, with the following terminal command:\
`export REDIVIS_API_TOKEN = 'MY_API_TOKEN'`

{% hint style="warning" %}
**IMPORTANT**: API access tokens operate like passwords, and can allow another party to access resources on your behalf.

You should never share tokens, and avoid committing to source control where collaborators may have access (either now or in the future). See the [Deploy and share your site](#id-5.-deploy-and-share-your-site) section below for details on how to use secrets to store a Redivis API token necessary for your project.
{% endhint %}

#### Writing a "data loader"

In Observable, a [data loader](https://observablehq.com/framework/loaders) is a file that accesses data and writes it to a standard output channel for consumption by renderers, to be ultimately displayed on your site.

In our example, we'll illustrate use of both javascript and python to pull data from Redivis into our dashboard, using the [Redivis API](https://app.gitbook.com/o/-LAzxbDPgjEGJfV0tvZu/s/GCgH8jTSmY8Vgwceiri5/) via js and python client libraries.

#### Using the redivis-js client library

In a web environment, the [redivis-js client library](https://app.gitbook.com/s/GCgH8jTSmY8Vgwceiri5/client-libraries/redivis-js) allows for fetching and manipulating data via simple javascript functions.

In our example, we first install the library by specifying the [latest version](https://www.npmjs.com/package/redivis) in our `package.json` and running `npm install` in our development environment to install or update all specified packages.

Then, in the Observable data loader file [`redivis-js-precipitation.json.js`](https://github.com/redivis/observable/blob/main/docs/data/redivis-js-precipitation.json.js) , we `authorize` access, and then `listVariables` and `listRows` from our specified precipitation table.

#### Using the redivis-python client library

In a python environment, the [redivis-python client library](https://app.gitbook.com/s/GCgH8jTSmY8Vgwceiri5/client-libraries/redivis-python) allows for fetching and manipulating data via simple python functions.

{% hint style="warning" %}
Using the redivis-python client library requires that you develop your web application in a virtual python environment. Observable documents this process [here](https://observablehq.com/framework/loaders#execution) – essentially, create an environment with [uv](https://github.com/astral-sh/uv), activate it on your machine, and install relevant packages to the environment.
{% endhint %}

In our example, we'll create a `requirements.txt` file that specifies the [latest version](https://pypi.org/project/redivis/) of the client library, both for development and future deployment.  Running the following command in your virtual python environment will install pip, and then any package specified in the requirements.txt file.

```
python3 -m pip install --upgrade pip
pip install -r requirements.txt
```

Then, in the Observable data loader file [`redivis-python-geodata.json.py`](https://github.com/redivis/observable/blob/main/docs/data/redivis-python-geodata.json.py) , we create a [pandas dataframe](https://app.gitbook.com/s/GCgH8jTSmY8Vgwceiri5/client-libraries/redivis-python/reference/table/table.to_pandas_dataframe) from our specified stations table, and output the records.

## 4. Visualize data

With data loaded and parsed into JSON format, it can now be manipulated and presented as you see fit. Among a wealth of modern web visualization tools is [Observable Plot](https://observablehq.com/plot/), which provides a polished selection of simple visualizations and corresponding functions to group and filter data, and pairs nicely with our development framework.

<figure><img src="https://1672950126-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LVodLwUXgJUGcm5Cvso%2Fuploads%2FLdPNwALLIQmRwHNNpaQH%2FScreenshot%202024-04-24%20at%2012.15.22%20PM_out.png?alt=media&#x26;token=9e840023-0621-418d-9ecf-d4c52f3348d8" alt=""><figcaption><p>Observable interactive visualzations</p></figcaption></figure>

In our example, we use several Observable Plot functions to display our data on a map – using [`Plot.plot()`](https://observablehq.com/plot/features/plots) with [`Plot.geo()`](https://observablehq.com/plot/marks/geo) to show a globe – and in a hex-binned histogram – using [`Plot.dot()`](https://observablehq.com/plot/marks/dot) and [`Plot.hexgrid()`](https://observablehq.com/plot/transforms/hexbin) for data aggregation. We also add a [range input](https://observablehq.com/framework/inputs/range) to allow viewers to rotate the globe visualization.

<figure><img src="https://1672950126-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LVodLwUXgJUGcm5Cvso%2Fuploads%2FXTKdXLzU1erh6jDYhyY6%2FScreenshot%202024-04-24%20at%2012.20.48%20PM_out.png?alt=media&#x26;token=35c5ba76-6a1b-4e67-be89-672d66ae9c15" alt=""><figcaption><p>Raw data used to build the above globe and histogram plots</p></figcaption></figure>

Then, we use the built-in [`display`](https://observablehq.com/framework/javascript#explicit-display) command to print the JSON-shaped payloads, to give the viewer a quick look at the raw data.

## 5. Deploy and share your site

With our dashboard finalized, you can deploy your project anywhere on the web. Observable provides a quick command (`npm run build`) to generate static files to be hosted on a server of your choice, as well as a deployment service if you'd like to host with Observable.

#### Deploying to Observable

You can run `npm run deploy` in the command line, and follow the prompts to [deploy](https://observablehq.com/framework/deploying#manual-deploys) your project to an address on Observable. Further configuration and permissioning is available through your Observable account.

#### Deploying to Github Pages

Github Pages provides a hosting service that's easy to integrate with your Github repository and any Github Actions needed to deploy your project.

In our example, we deployed our project to Github Pages in a few simple steps.

First, we need to specify a `REDIVIS_API_TOKEN` to support Redivis client library authorization in the live deployment. We used "action secret" within the Settings of the Github repo, which sets an environment variable `REDIVIS_API_TOKEN` to our appropriately scoped token, which is completely private while our repository remains public.

Next, we write a Github Action to build and deploy the project, which will run anytime we push to the main branch of our repository. The action is specified via the [`deploy.yaml`](https://github.com/redivis/observable/blob/main/.github/workflows/deploy.yaml) file, and relies on a set of open-source actions and our own custom code to do the following steps:

* Checkout the code
* Set up a Node.js environment, with a specific node version (`20.6`)
* Install our python dependencies (via `pip`,specified in `requirements.txt`)
* Build the static files for the site
* Deploy the files (in the generated `dist` folder) to Github Pages via a specific branch (`gh-pages`)

After adding this file to your Github repository, any push to the `main` branch will trigger a deployment following the steps above, the status of which can be viewed under the [Actions](https://github.com/redivis/observable/actions) tab of the repository.

Finally, Redivis has hosted a number of different team projects at a custom endpoint specified in our organization's Github Pages settings, which you can see at [labs.redivis.com](https://labs.redivis.com).