Connect API data

Choose your starting point

For CSV/JSON files or a snapshot URL, start with Bring your data. The recipes here use Studio's separate JSON adapter and input limits.

Quartile accepts rows and field metadata. Your application owns requests, authorization, caching and refresh. Studio combines three real public API templates with a visual editor; its exported starter contains native React components and the same data helper.

For an existing app, follow Installation and copy the standalone public helper into your app as quartile-data.ts. It is example application code, not an export from @quartile/react. To build visually, start with the Studio guide.

// Copy the public example helper as quartile-data.ts,
// or use the matching helper in a Studio export.
import { loadSource } from './quartile-data';

const controller = new AbortController();
const result = await loadSource({ kind: 'weather' }, {
  signal: controller.signal,
});
// result.data is a Dataset with rows, schema, labels and units.
// Keep result.attribution, warnings, requestedURL and fetchedAt.
// Abort on cancellation or when the request is superseded:
// controller.abort();

The helper returns data, label, requestedURL, fetchedAt, attribution and warnings. The timestamp records client receipt and validation, not the provider's publication time. Keep those distinctions visible in your application.

import { QuartileProvider, Selection, LineChart, DataExplorer } from '@quartile/react';
import type { Dataset, Row } from '@quartile/react';
import '@quartile/react/styles.css';

export function Forecast({ data }: { data: Dataset<Row> }) {
  return <QuartileProvider><Selection>
    <LineChart data={data} x="time" y="temperatureC" brush
      aria-label="Forecast temperature in degrees Celsius" />
    <DataExplorer data={data} rowKey="time" columns={[
      { field: 'time' }, { field: 'temperatureC' },
      { field: 'humidityPct' }, { field: 'precipitationMm' },
      { field: 'windSpeedKmh' },
    ]} />
  </Selection></QuartileProvider>;
}

Weather: hourly forecasts

Open the weather template. It requests seven days of hourly model forecasts for New York from the Open-Meteo Forecast API, with explicit UTC, Celsius, millimetres and kilometres per hour. Response units and parallel array lengths are checked before creating rows.

Use time and temperature for a line, wind speed for a distribution, and a table for exact values. These are forecasts, not measured station observations. The mean temperature describes the returned forecast hours. Humidity values are already 0–100; applying a 0–1 percent formatter would multiply them again.

Earthquakes: event records

Open the earthquakes template. The USGS past-day GeoJSON feed returns reported events. The adapter validates the feature collection and event count, then flattens the point coordinates.

https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_day.geojson

Scatter depth against magnitude and inspect individual reports in the table. Magnitude is logarithmic, may use different types and must not be summed. Depth can be negative, and network reference methods differ. The feed includes other reported event types and preliminary values may change. It is not an alert service. See ComCat field definitions.

USGS updates the feed every minute; Studio fetches on load or explicit refresh. Credit the U.S. Geological Survey. Its copyright policy places USGS-produced data in the U.S. public domain and identifies marked third-party exceptions.

Development: country-year observations

Open the development template. World Bank indicator SP.DYN.LE00.IN describes total life expectancy at birth in years. The preset selects twelve countries and 2014–2023. Each row contains country, countryCode, numeric year and nullable lifeExpectancyYears.

https://api.worldbank.org/v2/country/USA;CAN;BRA;GBR;DEU;FRA;IND;CHN;JPN;AUS;ZAF;NGA/indicator/SP.DYN.LE00.IN?date=2014:2023&format=json&per_page=5000

Map year to x, life expectancy to y and country to series. One row per country/year avoids duplicate coordinates. The cross-country mean is unweighted and must not be labeled global life expectancy. This historical window is not a current-year forecast.

The API requires no key. Its call contract defaults to XML and 50 records per page. This request explicitly chooses JSON and a page size; the adapter verifies page, pages and total and rejects partial results. Expand the query only with bounded pagination and validation. Intentional country codes avoid mixing country records with regional aggregates.

Missing observations remain null. The indicator is CC BY 4.0; retain World Bank World Development Indicators credit and the named underlying providers: UN World Population Prospects, national statistical offices and Eurostat.

Connect your own public JSON

const result = await loadSource({
  kind: 'custom',
  url: 'https://your-public-api.example/observations',
  rowsPath: 'data.observations',
}, { signal: controller.signal });

Replace this placeholder URL with a public HTTPS endpoint that permits browser CORS and your intended use. The request omits credentials and rejects redirects. Without a path, the adapter accepts an array or an object with a rows array. A path is a dot-separated property path, not JSONPath or a script.

Records must be flat objects containing strings, finite numbers, booleans or null. Nested arrays and objects need flattening first. Missing keys become null. Numeric columns are quantitative, booleans stay boolean, and mixed primitive columns are nominal. Date-looking and numeric strings stay nominal; large identifiers should stay strings. The adapter does not infer custom dates or provide arbitrary transformations.

In native React, validate a custom date column and its timezone, then declare it temporal with dataset(rows, schema). Studio does not expose custom schema editing. An epoch number can be a numeric x field, but its labels and formatting must explain that it represents time.

Requests, freshness and failures

• Show idle, loading, success, empty, error and cancelled states distinctly.
• Abort on unmount or source changes and ignore stale results. A retry starts a new request.
• Never replace failed or missing data with a plausible fixture or zero.
• Retain attribution, units, requested scope and receipt time. There is no automatic polling.
• UTC instants may display in the browser's time zone; make that choice explicit.

The short fetch fragment above is not a complete request UI. Studio and its generated starter implement the lifecycle. Charts also expose loading/error/empty props for application-owned requests. See Framework integration.

The three preset endpoints completed real cross-origin requests in an isolated Chromium browser on 2026-10-10. This demonstrates the tested behavior, not a future CORS or uptime guarantee. These adapter limits are separate from core library capacity; see bounded worker queries for larger data.