# API quickstart

Hubungi Google Search dan YouTube APIs secara langsung di atas HTTP. Kirim satu permintaan dan baca respon JSON; tidak diperlukan SDK.

Referensi kanonikal: https://flashdata.dev/id/docs/guides/http-quickstart
Diulang: 2026-11-04 oleh FlashData

<a id="application"></a>

## Buat permintaan HTTP pertamamu

Atur kunci API Anda, kirim satu pencarian Google dan periksa respon yang tersimpan.


<a id="prepare"></a>

### Otentikasi

Buat akun, verifikasi surel Anda dan buat kunci dengan izin Google Search. Anda dapat menggunakan kembali kunci yang telah ada.

Jalankan di terminal dan tempel key pada prompt yang menyembunyikan input. Lewati langkah ini jika FLASHDATA_API_KEY sudah diatur.

#### Bash

##### Atur key Anda

```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
```


#### PowerShell 7

##### Atur key Anda

```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 flashdataSecureKey
```


- [Buat akun](https://flashdata.dev/signup)
- [Buka API Keys](https://flashdata.dev/app/api-keys)
- [Otentikasi agen](https://flashdata.dev/auth.md)

<a id="curl"></a>

### Jalankan pencarian

Pilih klien dan jalankan contoh di terminal yang sama. Masing-masing mengirimkan satu POST permintaan untuk https://data.flashdata.dev/v1/queries/realtime dan cetakan JSON. Authentikasi dengan X-API-Key; kirim JSON dengan Content-Type: application/json.

#### cURL

cURL 7.76+ · Bash nyala Linux, macOS atau Git Bash. Tempel dan lari.

##### Cari Bash / cURL

```bash
curl --fail-with-body --silent --show-error --max-time 70 \
  --request POST https://data.flashdata.dev/v1/queries/realtime \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}'
```


#### PowerShell 7

PowerShell 7 + ini adalah perintah asli PowerShell.

##### Cari PowerShell

```powershell
$flashdataRequest = '{"source":"google_search","query":"battery recycling research","params":{"num":5}}'
$flashdataSearch = @{
  Uri = 'https://data.flashdata.dev/v1/queries/realtime'
  Method = 'Post'
  Headers = @{ 'X-API-Key' = $env:FLASHDATA_API_KEY }
  ContentType = 'application/json'
  Body = $flashdataRequest
  TimeoutSec = 70
  MaximumRedirection = 0
  SkipHttpErrorCheck = $true
  ErrorAction = 'Stop'
}
$flashdataResponse = Invoke-WebRequest @flashdataSearch
$flashdataResponse.Content
if ($flashdataResponse.StatusCode -ge 400) {
  throw "HTTP $($flashdataResponse.StatusCode). Inspect the response above before retrying."
}
```


#### JavaScript

Node.js 22Simpan sebagai search.mjs dan menjalankan lokal atau pada server Anda. Penggunaan built-in fetch; tidak ada npm install.

##### search.mjs

```javascript
const key = process.env.FLASHDATA_API_KEY;
if (!key) throw new Error("Set FLASHDATA_API_KEY in this terminal.");

let response;
try {
  response = await fetch("https://data.flashdata.dev/v1/queries/realtime", {
    method: "POST",
    redirect: "error",
    signal: AbortSignal.timeout(70000),
    headers: { "X-API-Key": key, "Content-Type": "application/json" },
    body: JSON.stringify({"source":"google_search","query":"battery recycling research","params":{"num":5}}),
  });
} catch {
  throw new Error("Request did not complete. Check History before resubmitting.");
}

const body = await response.text();
console.log(body); // Print the full response before checking its status.
if (!response.ok) {
  const retryAfter = response.headers.get("retry-after");
  throw new Error("HTTP " + response.status + ". See the response above." +
    (retryAfter ? " Retry-After: " + retryAfter : ""));
}
let result;
try {
  result = JSON.parse(body);
} catch {
  throw new Error("Expected JSON. Inspect the response above and the API URL.");
}
if (!result || result.error === true || result.status !== "done" || !Array.isArray(result.results)) {
  throw new Error("Query did not succeed. Inspect status and error in the response above.");
}
```

##### Jalankan JavaScript

```bash
node search.mjs
```


#### Python

Python 3.10Simpan sebagai search.py. Gunakan hanya perpustakaan standar; tidak ada instalasi pip. Gunakan python3 atau py -3 jika itu adalah perintah Python Anda.

##### search.py

```python
import json
import os
import urllib.error
import urllib.request

key = os.environ.get("FLASHDATA_API_KEY")
if not key:
    raise SystemExit("Set FLASHDATA_API_KEY in this terminal.")

# Do not forward the API key to a redirect destination.
class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

request = urllib.request.Request(
    "https://data.flashdata.dev/v1/queries/realtime",
    data=json.dumps({"source":"google_search","query":"battery recycling research","params":{"num":5}}).encode("utf-8"),
    headers={"X-API-Key": key, "Content-Type": "application/json"},
    method="POST",
)
try:
    with urllib.request.build_opener(NoRedirect).open(request, timeout=70) as response:
        body = response.read().decode("utf-8")
except urllib.error.HTTPError as error:
    print(error.read().decode("utf-8", errors="replace"))
    retry_after = error.headers.get("Retry-After")
    raise SystemExit("HTTP " + str(error.code) + ". See the response above." +
                     (" Retry-After: " + retry_after if retry_after else ""))
except (urllib.error.URLError, TimeoutError):
    raise SystemExit("Request did not complete. Check History before resubmitting.")

print(body)  # The run command saves this full response to result.json.
try:
    result = json.loads(body)
except json.JSONDecodeError:
    raise SystemExit("Expected JSON. Inspect the response above and the API URL.")
if (not isinstance(result, dict) or result.get("error") is True
        or result.get("status") != "done" or not isinstance(result.get("results"), list)):
    raise SystemExit("Query did not succeed. Inspect status and error in the response above.")
```

##### Jalankan Python

```bash
python -X utf8 search.py
```



<a id="result"></a>

### Periksa hasil

Konfirmasi keberhasilan HTTP dan status: done. Baca judul sumber, links dan snippet dalam results[].organic, dan muatan dalam usage.credits.

Hasil kosong atau daftar organik dengan status: done adalah hasil kosong yang valid.

| Ruas | Gunakan untuk |
| --- | --- |
| status | "done" mengkonfirmasi query telah selesai dengan sukses. |
| results[0].organic[] | Hasil pencarian. Periksa hasil yang tidak kosong sebelum mengindeksinya. |
| title / link / snippet | Judul sumber, URL dan excerpt. |
| usage.credits | Kredit Actual charged for this query. |

#### Respon contoh

```json
{
  "source": "google_search",
  "status": "done",
  "results": [
    {
      "organic": [
        {
          "title": "Battery recycling research",
          "link": "https://example.org/recycling",
          "snippet": "An example search excerpt."
        }
      ]
    }
  ],
  "usage": {
    "credits": 0.02
  }
}
```


<a id="diagnostics"></a>

## Simpan respon untuk debug

Untuk mengambil permintaan selanjutnya, tambahkan opsi ini ke perintah cURL di atas. Inspeksi berkas sebelum memutuskan untuk mencoba ulang permintaan yang gagal.

### cURL

```bash
--dump-header response-headers.txt --output result.json
```

- [Kesalahan HTTP dan pemulihan](https://flashdata.dev/id/docs/errors/reference.md)

<a id="check"></a>

## Periksa akses dan kredit

Ini permintaan GET membaca identitas, keseimbangan dan harga tanpa menggunakan kredit query. Diharapkan HTTP 200 dan memeriksa bidang di bawah ini sebelum mengirimkan pekerjaan yang dibayar.

Akun berbunyi: https://api.flashdata.dev/v2. Permintaan data: https://data.flashdata.dev/v1. Keduanya menggunakan X-API-Key; JSON POST permintaan juga menggunakan Content-Type: application/json.

| Baca | Apa yang harus diperiksa dalam respon |
| --- | --- |
| identity | Konfirmasikan yang dimaksudkan accountId, access: "ready", scopes berisi "google_search", dan apapun expiresAt. accountType adalah "owned" untuk kunci pemilik atau "temporary" untuk kunci percobaan. |
| balance | Baca availableCredits. Semua kunci untuk akun ini memakai keseimbangan yang sama. |
| pricing | Untuk harga [0], konfirmasi sumber adalah google_search dan tersedia adalah true. Bandingkan estimatedCredits untuk requestCount: 1 dengan availableCredits. Harga dan keseimbangan bisa berubah sebelum penyerahan. |

### Bash / cURL

#### Cek gratis Bash

```bash
(
for endpoint in 'identity' 'balance' 'pricing?source=google_search&request_count=1'; do
  printf '\n%s\n' "$endpoint"
  curl --fail-with-body --silent --show-error --max-time 20 \
    --header "X-API-Key: $FLASHDATA_API_KEY" \
    --write-out '\nHTTP %{http_code}\n' \
    "https://api.flashdata.dev/v2/api-access/$endpoint" || exit
done
)
```


### PowerShell 7

#### Cek gratis PowerShell

```powershell
try {
  foreach ($flashdataPath in @('identity', 'balance', 'pricing?source=google_search&request_count=1')) {
    Write-Host $flashdataPath
    $flashdataRead = @{
      Uri = "https://api.flashdata.dev/v2/api-access/$flashdataPath"
      Headers = @{ 'X-API-Key' = $env:FLASHDATA_API_KEY }
      TimeoutSec = 20
      MaximumRedirection = 0
      ErrorAction = 'Stop'
    }
    Invoke-RestMethod @flashdataRead | ConvertTo-Json -Depth 20
  }
} catch {
  throw
}
```



<a id="next"></a>

## Langkah selanjutnya

- [Google Search latihan terbaik](https://flashdata.dev/id/docs/guides/google-search-guide/reference.md)
- [YouTube Data](https://flashdata.dev/id/docs/guides/youtube-data-guide/reference.md)
- [YouTube Download](https://flashdata.dev/id/docs/guides/youtube-download-guide/reference.md)
- [Referensi API](https://flashdata.dev/id/docs/api-reference/reference.md)
- [Spesifikasi OpenAPI](https://flashdata.dev/docs/openapi.json)

<a id="troubleshooting"></a>

## Jika satu langkah gagal

Baca respon yang dicetak di terminal Anda. JavaScript dan Python melaporkan kesalahan HTTP dan Retry-After ke stderr. Setiap contoh menyerah sekali, tidak secara otomatis mencoba kembali.

| Symptom | Aksi berikutnya |
| --- | --- |
| Perintah hilang atau pilihan tidak didukung | Periksa versi yang diperlukan dalam contoh yang dipilih. Gunakan PowerShell 7 daripada Windows PowerShell 5.1, atau gunakan Bash dengan cURL 7.76+. JavaScript membutuhkan Node 22 +; Python kebutuhan 3.10+. Pasang waktu jalan yang hilang dari halaman pengunduhan resminya, buka kembali terminal, lalu atur lagi kuncinya. |
| Kehilangan kunci / 401 | Atur FLASHDATA_API_KEY dalam proses ini dan periksa identitas lagi. Menyediakan kunci API yang aktif secara penuh, tanpa awalan Pemula. Bila kadaluarsa atau dicabut, gunakan kredensial resmi saat ini; jangan tempelkan ke percakapan. |
| 403 | Periksa identity.scopes untuk google_search dan akses untuk siap. Permintaan izin yang hilang dari pemilik; mengubah sumber dalam permintaan tidak memberikan akses. |
| 402 | Baca saldo lagi dan bandingkan dengan harga saat ini. Pemilik dapat meninjau Billing. Sebuah percobaan yang melelahkan membutuhkan akses pemilik melalui klaim; menciptakan percobaan pengganti bukanlah pemulihan. |
| 400 / 422 | Baca pesan galat yang dikembalikan. Periksa host data yang tepat, metoda POST, Content-Type dan nama field JSON. Gunakan kutipan lurus dan numerik params.num, lalu perbaiki permintaan ditolak. |
| 429 | Menghormati Retry-After jika ada saat ini; sebaliknya gunakan sebuah baunded backoff dan kurangi konkuensi. Jangan loop dengan cepat, buat kunci baru atau daftar percobaan lain untuk melewati batas. |
| HTTP 200 dengan status atau error gagal | Baca kesalahan dalam tubuh dan melestarikan permintaan atau pekerjaan ID. Jangan perlakukan tubuh JSON yang diurai sebagai tugas yang sukses atau secara otomatis mengirimkannya kembali. |
| Hasil kosong | Jika status selesai, otentikasi bekerja. Simpan hasil kosong atau coba query lebih luas sebagai permintaan baru yang dibayar. |
| Tenggat waktu, kehilangan koneksi, 5xx atau HTML bukan JSON | Sebuah POST mungkin telah diterima bahkan jika respon telah hilang. Periksa History untuk query asli dan jaga kembali IDs sebelum memutuskan untuk mengirim kembali. Cek GET gratis dapat dicoba kembali. Konfirmasikan URL menggunakan data.flashdata.dev, bukan host website, dan jangan menonaktifkan verifikasi TLS. |

- [Meminta riwayat](https://flashdata.dev/app/jobs)
- [Kelola kunci](https://flashdata.dev/app/api-keys)
- [cURL unduhan](https://curl.se/download.html)
- [Pasang PowerShell](https://learn.microsoft.com/powershell/scripting/install/installing-powershell)
- [Node.js unduhan](https://nodejs.org/en/download)
- [Python unduhan](https://www.python.org/downloads/)
