# API faststart

اتصل Google Search و YouTube APIs directly over HTTP. أرسلي طلباً واحداً وقرأي JSON الرد؛ لا SDK مطلوب.

مرجع كانوني: https://flashdata.dev/ar/docs/guides/http-quickstart
Reviewed: 2026-11-04 by FlashData

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

## إجعلْك أولاً HTTP الطلب

جهزوا API مفتاح، أرسل واحدة Google ابحث وفتش الاستجابة الموفرة


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

### التوثيق

إنشاء حساب، والتحقق من البريد الإلكتروني الخاص بك وخلق مفتاح مع Google Search إذن. يمكنك إعادة استخدام المفتاح الحالي.

شغّل الأمر في الطرفية والصق المفتاح عند مطالبة الإدخال المخفي. تجاوز هذه الخطوة إذا كان FLASHDATA_API_KEY مضبوطًا بالفعل.

#### Bash

##### اضبط المفتاح

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

##### اضبط المفتاح

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


- [إنشاء حساب](https://flashdata.dev/signup)
- [فتح API Keys](https://flashdata.dev/app/api-keys)
- [التوثيق من قبل العميل](https://flashdata.dev/auth.md)

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

### نفّذ بحثًا

اختر زبوناً و اضرب المثل في نفس المحطة ويرسل كل منها طلباً واحداً من طراز POST إلى https://data.flashdata.dev/v1/queries/realtime وطبعات من طراز JSON. Authenticate with X-API-Key; send JSON with Content-Type: application/json.

#### cURL

cURL 7.76+ · Bash على Linux أو macOS أو Git Bash. الصق وشغّل.

##### / / 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+ ; Paste this native PowerShell command.

##### باحثة: 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 22+ · احفظ باسم search.mjs وشغّله محليًا أو على خادمك. يستخدم fetch المضمّن؛ ولا يحتاج 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.");
}
```

##### JavaScript

```bash
node search.mjs
```


#### Python

Python 3.10+  Save as search.py. لا تستخدم سوى المكتبة الموحدة؛ ولا يوجد مخزون من الـ pip. إستعملْ Python3 أَو py -3 إذا ذلك هو قائدُ Python.

##### 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.")
```

##### Python

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



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

### تحقق من النتيجة

تأكد من نجاح HTTP ووجود status: done. اقرأ عناوين المصادر وروابطها ومقتطفاتها في results[].organic والتكلفة في usage.credits.

وتشكل النتائج الفارغة أو القائمة العضوية مع status: done نتيجة فارغة صالحة.

| الميدان | إستخدمه |
| --- | --- |
| status | "done" يؤكد أن الإستفسار انتهى بنجاح. |
| results[0].organic[] | نتائج البحث. تحقق من أن النتائج غير فارغة قبل فهرسة لها. |
| title / link / snippet | المصدر: URL و excerpt. |
| usage.credits | المبالغ الفعلية المقيدة على هذا الاستفسار. |

#### الاستجابة على سبيل المثال

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

## أنقذوا ردّاً على التشويه

ولتلبية الطلب التالي المعتزم، تضاف هذه الخيارات إلى قيادة cURL أعلاه. فحص الملفات قبل أن يقرر إعادة النظر في طلب فاشل

### cURL

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

- [HTTP الأخطاء والانتعاش](https://flashdata.dev/ar/docs/errors/reference.md)

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

## الوصول إلى السجلات والائتمانات

وتُقرأ هذه الطلبات التي تقدمت بها شركة GET تحت عنوان " الهوية والتوازن والتسعير " دون استخدام ائتمانات الاستفسارات. التوقعات HTTP 200 وتحقق من الحقول الواردة أدناه قبل تقديم العمل المدفوع الأجر.

قراءات الحساب: https://api.flashdata.dev/v2. طلبات البيانات: https://data.flashdata.dev/v1. يستخدم كلاهما X-API-Key؛ وتستخدم طلبات JSON POST أيضًا Content-Type: application/json.

| اقرأ | ما الذي يجب التحقق منه في الرد |
| --- | --- |
| identity | تحقق من accountId المقصود وaccess: "ready" واحتواء scopes على "google_search"، ومن أي قيمة expiresAt. تكون accountType هي "owned" لمفتاح المالك أو "temporary" لمفتاح التجربة. |
| balance | إقرأْ availableCredits. جميع مفاتيح هذا الحساب تستخدم نفس التوازن |
| pricing | For prices[0], confirm source is google_search and available is true. Compare estimatedCredits for requestCount: 1 with availableCredits. ويمكن أن تتغير الأسعار والأرصدة قبل التقديم. |

### Bash / cURL

#### فحوص مجانية؛ 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

#### فحوص مجانية؛ 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>

## الخطوات التالية

- [Google Search أفضل الممارسات](https://flashdata.dev/ar/docs/guides/google-search-guide/reference.md)
- [YouTube Data](https://flashdata.dev/ar/docs/guides/youtube-data-guide/reference.md)
- [YouTube Download](https://flashdata.dev/ar/docs/guides/youtube-download-guide/reference.md)
- [مرجع API](https://flashdata.dev/ar/docs/api-reference/reference.md)
- [المواصفات المفتوحة](https://flashdata.dev/docs/openapi.json)

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

## إذا فشلت خطوة

اقرأ الاستجابة المطبوعة في الطرفية. تعرض JavaScript وPython أخطاء HTTP وRetry-After على stderr. يرسل كل مثال مرة واحدة؛ ولا يعيد المحاولة تلقائيًا.

| الرمز | الإجراء التالي: |
| --- | --- |
| خيار القيادة المفقود أو غير المدعوم | تحقق من النسخة المطلوبة في المثال المختار. الاستخدام PowerShell 7 بدلاً من Windows PowerShell 5.1أو استخدام Bash مع cURL 7.76+. JavaScript needs Node 22+; Python needs 3.10+. ضعوا الوقت المفقود من موقع تحميلها الرسمي، وأعيدوا فتح المحطة، ثم أعدوا المفتاح مرة أخرى. |
| مفتاح مفقود/ 401 | المجموعة FLASHDATA_API_KEY في هذه العملية وتحقق من الهوية مرة أخرى توفير كامل النشاط API مفتاح، بدون بيير بيكس وإذا انقضت أو ألغيت، استخدم عقيدة مأذون بها حاليا؛ ولا تتدخل في الحديث. |
| 403 | تحقق identity.scopes for google_search و الدخول للاستعداد طلب الإذن المفقود من المالك؛ تغيير المصدر في الطلب لا يمنح إمكانية الوصول. |
| 402 | اقرأ التوازن مرة أخرى وقارنه بالثمن الحالي المالك يمكنه أن يستعرض Billing. وتحتاج التجربة المستنفدة إلى وصول المالك من خلال المطالبة؛ ولا يُسترجع إنشاء تجربة بديلة. |
| 400 / 422 | اقرأ رسالة الخطأ المعادة تحقق من مضيف البيانات الدقيق، وطريقة POST، و Content-Type، و JSON الاسمان الميدانيان. استخدام الاقتباسات المستقيمة والرقمية params.numثم تصحيح الطلب المرفوض. |
| 429 | (ب) احترام الـ (زكس كيزوك (Retry-After) إذا كان موجوداً؛ وخلافاً لذلك، استخدام التخلف المقيد والحد من الاتّفاق. لا تدور بسرعة، وتصنع مفاتيح جديدة أو تسجل تجربة أخرى لتجاوز الحدود. |
| HTTP 200 with failed status or error | اقرأ الخطأ في الجسم وحافظ على أي طلب أو وظيفة ID. لا تعاملوا هيئة من طراز JSON على أنها مهمة ناجحة أو إعادة تقديمها تلقائياً. |
| نتائج فارغة | إذا تم تحديد الوضع، فإن التوثيق يعمل. أبقوا النتيجة الفارغة أو حاولوا أن يُستفسروا على نطاق أوسع كطلب جديد مدفوع الأجر. |
| وقت الاستراحة، فقدان الاتصال، 5x أو HTML بدلا من JSON | قد يكون POST قد قُبل حتى إن فُقدت استجابته. تحقق من الاستعلام الأصلي في History واحتفظ بأي معرّفات عائدة قبل تقرير إعادة الإرسال. يمكن إعادة فحوص GET المجانية. تأكد من استخدام data.flashdata.dev وليس مضيف الموقع، ولا تعطّل التحقق من TLS. |

- [التاريخ](https://flashdata.dev/app/jobs)
- [مفاتيح إدارة](https://flashdata.dev/app/api-keys)
- [حمولات cURL](https://curl.se/download.html)
- [Install PowerShell](https://learn.microsoft.com/powershell/scripting/install/installing-powershell)
- [حمولات Node.js](https://nodejs.org/en/download)
- [حمولات Python](https://www.python.org/downloads/)
