STADATA JS SDK

Official TypeScript/JavaScript SDK for BPS (Badan Pusat Statistik) WebAPI — Seamlessly access Indonesia's Central Bureau of Statistics data through a comprehensive, type-safe client library.

Overview

The STADATA JS SDK provides TypeScript/JavaScript developers with streamlined access to Indonesia's statistical data through the official BPS WebAPI. Create data-driven applications featuring demographic, economic, and socio-economic information from Indonesia's most authoritative statistical source.

Features

• Functional Composable API — initStadata() + use*() composables by default, with optional explicit clients for advanced use cases
• Full TypeScript Support — Complete type definitions with IntelliSense support
• Result Pattern — Uses neverthrow for elegant, type-safe error handling
• Tree-shakeable — Only bundle what you use
• Pagination Support — Built-in pagination handling for all list endpoints
• Request Cancellation — Cancel ongoing requests to optimize performance
• Immutable Entities — Predictable, safe domain entities

Requirements

• Node.js >= 16.0.0
• Valid API key from BPS WebAPI platform

Installation

# npm
npm install stadata-js

# pnpm
pnpm add stadata-js

# yarn
yarn add stadata-js

Quick Start

import { initStadata, usePublications, useDomains, DataLanguage, DomainType } from 'stadata-js'

// 1. Initialize once at app entry point
initStadata({ apiKey: 'your-api-key-here' })

// 2. Use composables anywhere — no client reference needed
const { fetchPublicationList, fetchPublicationDetail } = usePublications()
const { fetchDomainList } = useDomains()

// 3. Fetch data
const result = await fetchPublicationList({
  domain: '7200',
  lang: DataLanguage.ID,
  page: 1,
  perPage: 10,
})

result.match(
  ({ data, pagination }) => {
    console.log(`Total: ${pagination.total}`)
    data.forEach(pub => console.log(pub.title))
  },
  (error) => console.error('Error:', error.message)
)

API Reference

Full documentation: ipds-59.github.io/stadata_js

Available Composables

| Composable | Functions | |-----------|-----------| | useDomains() | fetchDomainList | | usePublications() | fetchPublicationList, fetchPublicationDetail | | usePressReleases() | fetchPressReleaseList, fetchPressReleaseDetail | | useStaticTables() | fetchStaticTableList, fetchStaticTableDetail | | useDynamicTables() | fetchDynamicTableList | | useInfographics() | fetchInfographicList | | useNews() | fetchNewsList, fetchNewsDetail | | useNewsCategories() | fetchNewsCategoryList | | useVariables() | fetchVariableList, fetchVariableDetail | | useVerticalVariables() | fetchVerticalVariableList | | useDerivedVariables() | fetchDerivedVariableList | | useSubjects() | fetchSubjectList, fetchSubjectDetail | | useSubjectCategories() | fetchSubjectCategoryList | | useUnits() | fetchUnitList, fetchUnitDetail | | usePeriods() | fetchPeriodList | | useDerivedPeriods() | fetchDerivedPeriodList | | useStrategicIndicators() | fetchStrategicIndicatorList, fetchStrategicIndicatorDetail | | useStatisticClassifications() | fetchStatisticClassificationList, fetchStatisticClassificationDetail | | useCensus() | fetchCensusList | | useTrade() | fetchTradeData |

Error Handling

All functions return Result<T, ApiFailure> from neverthrow:

const result = await fetchPublicationList({ domain: '7200', lang: DataLanguage.ID })

// Option 1: match
result.match(
  ({ data, pagination }) => console.log(data),
  (error) => console.error(error.message)
)

// Option 2: guard check
if (result.isOk()) {
  const { data, pagination } = result.value
}

if (result.isErr()) {
  console.error(result.error.message)
}

Configuration

const stadata = createStadataClient({
  apiKey: 'your-api-key',       // required
  timeout: 15000,                // optional, ms (default: 30000)
  debug: true,                   // optional, enable debug logging
  baseURL: 'https://...',        // optional, custom base URL
})

Migration from v1

Version 2 introduces a breaking change from the class-based API to the composable API.

v1 (deprecated)

await StadataJS.init({ apiKey: 'key' })
const stadata = StadataJS.instance

const publications = await stadata.list.publications({
  domain: '7200',
  lang: DataLanguage.ID,
})

v2 (recommended)

import { initStadata, usePublications, DataLanguage } from 'stadata-js'

// initialize once at app entry point
initStadata({ apiKey: 'key' })

// use composables anywhere in your app
const { fetchPublicationList, fetchPublicationDetail } = usePublications()

const publications = await fetchPublicationList({
  domain: '7200',
  lang: DataLanguage.ID,
})

What changed

• StadataJS.init() → initStadata()
• StadataJS.instance.list.publications() → usePublications().fetchPublicationList()
• StadataJS.instance.view.publication() → usePublications().fetchPublicationDetail()
• list/view methods are now grouped by composable (useDomains, useNews, useDynamicTables, etc.)
• global initialization is the default pattern, so you no longer need to carry a singleton instance around your app

Advanced migration path

If you need multiple clients (for example different API keys), you can still use an explicit client:

import { createStadataClient, usePublications } from 'stadata-js'

const client = createStadataClient({ apiKey: 'other-key' })
const { fetchPublicationList } = usePublications(client)

StadataJS class is kept as @deprecated in v2 for transition purposes and will be removed in v3.

Advanced: Multiple Clients

If you need multiple clients (e.g. different API keys), use createStadataClient directly:

import { createStadataClient, usePublications } from 'stadata-js'

const client = createStadataClient({ apiKey: 'other-key' })
const { fetchPublicationList } = usePublications(client) // explicit client

License

MIT © IPDS-59