DataStreamJS

DataStream.org API helper. See API documentation for query string values and structure.

Install

npm install https://github.com/datastreamapp/datastreamjs

Use

This packages works in the browser and with NodeJS.

Set your API key

setAPIKey sends your key as the x-api-key header on every request, so call it once before any other method. See the API documentation for how to request a key and the terms of using it.

import { setAPIKey } from '@datastreamapp/datastreamjs'

setAPIKey('xxxxxxxxxx') // secrets should be injected securely

Identify your application

Every request already identifies this package, for example datastreamjs/0.1.0 node/24.15.0. Use setUserAgent to name your own application alongside it, so DataStream can attribute traffic and diagnose slow or failing requests. The version is optional, and it does not matter whether you call it before or after setAPIKey.

import { setUserAgent } from '@datastreamapp/datastreamjs'

setUserAgent('MyProject', '1.0')
// User-Agent: MyProject/1.0 datastreamjs/0.1.0 node/24.15.0

The name must be a single token of letters, digits, ., _, + or -; anything else throws. Note that browsers drop User-Agent as a forbidden header name, so this only reaches the API from NodeJS.

Example

import {
  setAPIKey,
  setUserAgent,
  metadata,
  locations,
  records,
  observations
} from '@datastreamapp/datastreamjs'

setAPIKey('xxxxxxxxxx') // secrets should be injected securely
setUserAgent('MyProject', '1.0')

const observationsStream = await observations({
  $select:
    'DOI,ActivityType,ActivityMediaName,ActivityStartDate,ActivityStartTime,SampleCollectionEquipmentName,CharacteristicName,MethodSpeciation,ResultSampleFraction,ResultValue,ResultUnit,ResultValueType',
  $filter: `DOI eq '10.25976/xxxx-xx00'`,
  $top: 10000
})

for await (const observation of observationsStream) {
  // use record
}

Example: save to file

import { pipeline } from '@datastream/core'
import { csvFormatStream } from '@datastream/csv/format'
import { createWriteStream } from 'node:fs'

import {
  setAPIKey,
  metadata,
  locations,
  records,
  observations
} from '@datastreamapp/datastreamjs'

setAPIKey('xxxxxxxxxx') // secrets should be injected securely

const recordsStream = await records({
  $select:
    'DOI,ActivityType,ActivityMediaName,ActivityStartDate,ActivityStartTime,SampleCollectionEquipmentName,CharacteristicName,MethodSpeciation,ResultSampleFraction,ResultValue,ResultUnit,ResultValueType',
  $filter: `DOI eq '10.25976/xxxx-xx00'`,
  $top: 10000
})

await pipeline([
  recordsStream,
  csvFormatStream(),
  createWriteStream('/path/to/output.csv')
])

Example: result count

Pass $count as true to get the number of matching rows instead of the rows themselves. This returns the total directly rather than a stream. See URL parameters for more details.

import { setAPIKey, observations } from '@datastreamapp/datastreamjs'

setAPIKey('xxxxxxxxxx') // secrets should be injected securely

const count = await observations({
  $filter: `DOI eq '10.25976/xxxx-xx00'`,
  $count: 'true'
})

console.log(count) // '3930'