Skip to content
EN
Get API key
Browse documentation

Get started

Python SDK quickstart

Install the Python SDK and print search results with a few lines of code. Includes synchronous and asyncio examples.

  1. Install the SDK

    Requires Python 3.10+. Run these commands in your project directory. Already using a virtual environment? Install flashdata==1.1.0 with that environment's python -m pip instead.

    Install
    python3 -m venv .venv
    .venv/bin/python -m pip install "flashdata==1.1.0"
  2. Authenticate

    Create an API key with Google Search permission, or reuse an authorized key. Set it in this terminal using the hidden prompt below.

    Skip the prompt if FLASHDATA_API_KEY is already set. These examples read the variable directly; they do not load .env files.

    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 this as quickstart.py, then run it with the same virtual environment. It makes one Google Search request for up to five results and prints titles, URLs and credits used.

    quickstart.py
    import os
    from flashdata import FlashData
    
    with FlashData(api_key=os.environ["FLASHDATA_API_KEY"]) as client:
        response = client.google.search("battery recycling research", num=5)
        if response["status"] != "done":
            raise RuntimeError(response)
        for page in response["results"]:
            for hit in page.get("organic", []):
                print(hit["title"], hit["link"])
        print("Credits used:", response["usage"]["credits"])
    Run
    .venv/bin/python quickstart.py
  4. Check the result

    The script exits normally after checking status is done. Expect source titles and URLs followed by Credits used. An empty organic list is a valid response; results vary with your query.

    Example output
    Battery recycling research https://example.org/recycling
    Credits used: 0.02
    results[].organic[]
    Google Search hits: title, link and snippet. Other sources have different result fields.
    usage.credits
    Cost of this request. Up to five results here are one search request.

Try another data source

Each tab is a complete script. Replace quickstart.py with one example and run it with the command from step 3. Each run submits one new request; the key needs the source permission shown.

Requires google_news. Prints article titles and source links from results[].news[].

quickstart.py
import os
from flashdata import FlashData

with FlashData(api_key=os.environ["FLASHDATA_API_KEY"]) as client:
    response = client.google.news("battery recycling", num=5)
    if response["status"] != "done":
        raise RuntimeError(response)
    for page in response["results"]:
        for article in page.get("news", []):
            print(article.get("title"), article.get("link"))

What the Python SDK supports

google / youtube
Google Search, News, Images, Shopping, Videos and Places; YouTube discovery, metadata, captions, transcripts and channel data.
youtube.download
Submit an audio or video delivery job to your cloud storage. Requires youtube_download permission and storage configuration; follow the complete download example below.
jobs / bulk
Save the accepted job ID, wait for completion and retrieve results. Use bulk for larger video-ID datasets and resume existing jobs after a restart.
account
Read access, balance, pricing, limits and usage before recurring work. Reuse an authorized key from your environment or secret store.
respond_with / accept
Use respond_with="markdown" for Markdown in response["content"], or accept="text/plain" for a string. JSON dictionaries are the default.

Use asyncio

Replace quickstart.py with this version and use the same run command. AsyncFlashData exposes the same resources with await. This still waits for a realtime search response; mode="async" submits a server-side background job instead.

In Jupyter or an application with a running event loop, use await main() instead of asyncio.run(main()). Reuse the client within that event loop.

quickstart.py
import asyncio
import os
from flashdata import AsyncFlashData

async def main():
    async with AsyncFlashData(api_key=os.environ["FLASHDATA_API_KEY"]) as client:
        response = await client.google.search("battery recycling research", num=5)
        if response["status"] != "done":
            raise RuntimeError(response)
        for page in response["results"]:
            for hit in page.get("organic", []):
                print(hit["title"], hit["link"])
        print("Credits used:", response["usage"]["credits"])

asyncio.run(main())

Next steps

If a step fails

ModuleNotFoundError
Install and run with the same interpreter: .venv/bin/python -m pip show flashdata (Windows: .\.venv\Scripts\python.exe -m pip show flashdata). Do not name your script flashdata.py.
KeyError: FLASHDATA_API_KEY / 401
Set an active API key in the same terminal. A .env file alone is not loaded by this example. Use an API key, not an MCP OAuth token.
403
Grant the source permission required by the example to this key.
402
Check Billing for available credits. If trial access is exhausted, claim the connection to use your account balance.
429 / APIError
Inspect error.retry_after and reduce request rate. The SDK sends each request once and does not retry automatically.
SubmissionUnknownError
A timed-out submission may already be accepted. Check History before repeating it; reuse a saved job ID when available.
asyncio.run() / running event loop
Use await main() in a notebook or existing event loop. Keep asyncio.run(main()) for a standalone script.