Browse documentation
Get started
Install the Python SDK and print search results with a few lines of code. Includes synchronous and asyncio examples.
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.
Installpython3 -m venv .venv .venv/bin/python -m pip install "flashdata==1.1.0"Installpy -3 -m venv .venv .\.venv\Scripts\python.exe -m pip install "flashdata==1.1.0"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_KEYHidden key prompt · PowerShell# PowerShell 7: paste the key into a hidden prompt. $flashdataSecureKey = Read-Host "FlashData API key" -AsSecureString $env:FLASHDATA_API_KEY = [System.Net.NetworkCredential]::new("", $flashdataSecureKey).Password Remove-Variable flashdataSecureKeyRun 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.pyimport 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.pyRun.\.venv\Scripts\python.exe quickstart.pyCheck 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 outputBattery recycling research https://example.org/recycling Credits used: 0.02results[].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[].
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"))Requires youtube_metadata. Prints the video title, channel and duration in seconds. Replace the video ID with one you want to inspect.
import os
from flashdata import FlashData
with FlashData(api_key=os.environ["FLASHDATA_API_KEY"]) as client:
response = client.youtube.metadata("dQw4w9WgXcQ", include_formats=False)
if response["status"] != "done":
raise RuntimeError(response)
for video in response["results"]:
print(video.get("title"), video.get("channel"))
print("Seconds:", video.get("duration"))Requires youtube_transcript. Prints an existing English automatic transcript from results[].fullText. The video must have that track; this call does not generate or translate captions.
import os
from flashdata import FlashData
with FlashData(api_key=os.environ["FLASHDATA_API_KEY"]) as client:
response = client.youtube.transcript("dQw4w9WgXcQ", language="en", auto=True)
if response["status"] != "done":
raise RuntimeError(response)
for track in response["results"]:
print(track.get("fullText", ""))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.
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.