Skip to main content
Fetch a remote file by URL and parse it into the Data structure expected by @graphysdk/core. The format is auto-detected from the URL path extension.

​
fromURL

import { fromURL } from '@graphysdk/data-import-utils/url';

const data = await fromURL('https://example.com/sales.csv');
const data = await fromURL('https://example.com/report.xlsx', { sheet: 'Revenue' });

​
Signature

function fromURL(
  url: string,
  options?: URLParseOptions
): Promise<Data>

​
Options

​
url
string
required
URL to fetch. The path extension determines the format, falling back to the response Content-Type header.
​
options.headers
Record<string, string>
Custom headers to include in the fetch request. Useful for authenticated endpoints (e.g. { Authorization: 'Bearer token' }).
​
options.timeout
number
default:"30000"
Fetch timeout in milliseconds. The request is aborted if it takes longer.
​
options.signal
AbortSignal
Optional external abort signal for cancellation. Combined with the internal timeout signal via AbortSignal.any.
​
options.hasHeader
boolean
default:"true"
Whether the first row contains column headers (CSV/TSV only). When false, columns are auto-named Column 1, Column 2, etc.
​
options.sheet
string | number
default:"0"
Sheet to parse (spreadsheets only). Pass a sheet name or 0-based index.
​
options.locale
VizLocale
default:"EN_US"
Locale for number parsing. Determines thousand/decimal separator conventions.
​
options.maxFileSize
number
default:"5"
Maximum allowed input size in megabytes. The response body is streamed with a byte budget — the download is aborted early if the limit is exceeded.
​
options.maxRows
number
default:"100000"
Maximum number of data rows to process (spreadsheets only).
​
options.maxCells
number
default:"5000000"
Maximum total cells to process (spreadsheets only).

​
Supported Extensions

ExtensionFormat
.csvCSV
.tsv, .tabTSV
.xlsxXLSX
.xlsXLS
.odsODS
Unsupported extensions throw an error listing the supported formats.

​
Examples

​
With the AI SDK

import { fromURL } from '@graphysdk/data-import-utils/url';
import { GraphyAiSdk } from '@graphysdk/agents-sdk';

const ai = new GraphyAiSdk({
  apiKey: process.env.GRAPHY_API_KEY,
  baseUrl: 'https://agents.graphy.dev',
});

const data = await fromURL('https://data.example.com/quarterly-sales.csv');

const result = await ai.generateGraph({
  config: { data },
  userPrompt: 'line chart showing quarterly trends',
});

​
Error Handling

try {
  const data = await fromURL('https://example.com/data.pdf');
} catch (error) {
  // Error: Unsupported file extension ".pdf". Supported: .csv, .tsv, .tab, .xlsx, .xls, .ods
}

​
With Custom Headers

const data = await fromURL('https://api.example.com/data.csv', {
  headers: { Authorization: 'Bearer my-token' },
});

​
With Timeout and Cancellation

const controller = new AbortController();

const data = await fromURL('https://example.com/large-file.xlsx', {
  timeout: 10_000,
  signal: controller.signal,
});
SSRF Protection: fromURL validates URLs before fetching. Private and reserved IP addresses (e.g. 127.0.0.1, 10.x.x.x, 192.168.x.x, 169.254.x.x, localhost, IPv6 loopback/link-local) are blocked, and only http: and https: schemes are allowed. This prevents server-side request forgery when URLs are provided by end users.
fromURL uses the global fetch API and works in Node.js 18+ and all modern browsers. For authenticated endpoints, you can either pass headers in the options or fetch the data yourself and use the format-specific parsers (fromCSV, fromXLSX, etc.) directly.