Skip to content
EN
Get API key
Browse documentation

Get started

TypeScript & JavaScript SDK

Install the SDK and run a search in Node.js. Choose TypeScript or JavaScript; keep API keys on the server.

  1. Install the SDK

    These examples use Node.js 22.18+ to run TypeScript directly. Start in an empty folder, or select Existing project if you have package.json.

    Install
    npm init -y
    npm install --save-exact @flashdata-dev/[email protected]
  2. Authenticate

    Create a key with Google Search permission or reuse an authorized key. Set FLASHDATA_API_KEY in this terminal using the hidden prompt below; skip this if your environment already supplies it.

    The example passes the key explicitly. A .env file is not loaded by these scripts. Keep the key in server-side configuration when integrating into a web application.

    Hidden key prompt · Bash
    # Bash: paste the key into a hidden prompt, not into this command.
    read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
    printf '\n'
    export FLASHDATA_API_KEY
  3. Run a search

    Save the selected file and run its command in this project. Each run submits one search for up to five results. Both files run directly with Node.js; no build step is needed for this example.

    quickstart.mts
    import { FlashData, type GoogleSearchParams } from '@flashdata-dev/sdk';
    
    const apiKey = process.env.FLASHDATA_API_KEY;
    if (!apiKey) throw new Error('Set FLASHDATA_API_KEY in the server environment.');
    const client = new FlashData({ apiKey });
    const params: GoogleSearchParams = { num: 5 };
    const response = await client.google.search({ query: 'battery recycling research', ...params });
    if (response.status !== 'done') throw new Error(JSON.stringify(response));
    
    for (const page of response.results) {
      for (const hit of page.organic ?? []) console.log(hit.title, hit.link);
    }
    console.log('Credits used:', response.usage.credits);
    Run · Node.js 22.18+
    node quickstart.mts
  4. Check the result

    The script checks status is done and prints source titles, URLs and credits used. Empty organic results are valid. The example output below illustrates the shape; live sources will vary.

    Example output
    Battery recycling research https://example.org/recycling
    Credits used: 0.02
    results[].organic[]
    Google Search titles, links and snippets. Other sources have their own typed payloads.
    usage.credits
    Credits charged for this request; five returned hits are one search request.

Try another data source

Each tab works in both TypeScript and JavaScript. Replace the file from step 3, keep its .mts or .mjs extension and run the same command. Each run is a new request and needs the source permission shown.

Requires google_news. Read article entries in results[].news[].

quickstart.mts / quickstart.mjs
import { FlashData } from '@flashdata-dev/sdk';

const apiKey = process.env.FLASHDATA_API_KEY;
if (!apiKey) throw new Error('Set FLASHDATA_API_KEY first.');
const client = new FlashData({ apiKey });
const response = await client.google.news({
  query: 'battery recycling', num: 5,
});
if (response.status !== 'done') throw new Error(JSON.stringify(response));
console.log(response);

Type-check a TypeScript project

Node runs this example by stripping types. To check types without sending a request, install TypeScript and run the compiler with --noEmit:

Optional type check
npm install --save-dev typescript@~5.9.3 @types/node@^22
npx tsc quickstart.mts --module nodenext --target es2022 --strict --noEmit

What the SDK supports

google / youtube
Search and retrieve structured data with typed source helpers. Reuse one client in your service.
youtube.download
Deliver audio or video to your cloud storage through a background job. Requires youtube_download permission and storage configuration.
jobs / bulk
Save submitted job IDs and retrieve completed results. await waits in JavaScript; mode: 'async' submits a server-side background job.
account
Read access, balance, pricing, limits and usage before recurring work.
respondWith / accept
Pass { respondWith: 'markdown' } as the method's second argument for Markdown in response.content, or { accept: 'text/plain' } for a string. JSON objects are the default.

Next steps

If a step fails

Package or runtime missing
Check node --version and install @flashdata-dev/sdk in this project. Keep the .mts or .mjs extension shown above.
401 / FLASHDATA_API_KEY
Set a valid key in the terminal where you run the example.
403
Enable Google Search for this API key.
402
Check Billing for available credits, or claim an exhausted agent trial.
429
Wait for Retry-After, then reduce your request rate.
Timeout or server error
Check History before resending; the first request may already have run.