# YouTube Organic پیشرفته زنده

**API:** Data API

**Endpoint:** `POST /v1/beta/dataforseo/serp/youtube/organic/live/advanced`

**Tags:** DataForSEO

نتایج رتبه‌بندی‌شده برای یک کلیدواژه در YouTube را به‌صورت همگام برمی‌گرداند. `keyword`، `type`، `se_domain`، `location_code`، `language_code`، `check_url`، `datetime`، `spell`، `refinement_chips`، `item_types`، `items_count` و `items` را برمی‌گرداند. `advanced` انتخاب پیش‌فرض است؛ وقتی فقط فهرست رتبه‌بندی‌شده مهم است `regular` را بگیرید و `html` را فقط برای بررسی چیزی که تجزیه‌گر انداخته است. پاسخ در پاکت DataForSEO قرار می‌گیرد: داده‌ها در `tasks[0].result` و نتیجه در `tasks[0].status_code` — درخواست ردشده نیز همچنان HTTP 200 برمی‌گرداند.

### مرجع قیمت‌گذاری

- اندازه‌گیری: هزینه گزارش‌شده پاسخ.
- برآورد درخواست مرجع: 0.002 دلار آمریکا.
- ضریب مشتری مرجع: 1.0. آن را دوباره روی مبلغ تسویه‌شده مشتری اعمال نکنید.

فقط فراداده مرجع است، نه نقل‌قول حساب، نه قیمت تضمین‌شده و نه سقف هزینه. اعتبار منابع، اعتبار Felo نیست. هزینه‌های نهایی تابع سوابق صورت‌حساب Felo است.

## Base URL

- `https://openapi.felo.ai`

## Authentication

- `FeloBearerAuth` (http bearer, bearer format Felo API Key)
- `FeloApiKey` (apiKey in header `X-API-Key`)

## Request body

Required: **no**

### application/json

Schema:

```json
{
  "type": "array",
  "items": {
    "type": [
      "object",
      "null"
    ],
    "oneOf": [
      {
        "type": "object",
        "properties": {
          "keyword": {
            "type": "string",
            "description": "کلیدواژه\nفیلد الزامی\nمی‌توانید تا 700 کاراکتر در فیلد keyword تعیین کنید\nهمه %## رمزگشایی می‌شوند (و کاراکتر ‘+’ به فاصله رمزگشایی می‌شود)\nاگر باید از کاراکتر “%” در keyword استفاده کنید، آن را به‌صورت “%25” تعیین کنید؛\nاگر باید از کاراکتر “+” در keyword استفاده کنید، آن را به‌صورت “%2B” تعیین کنید؛\nدرباره قواعد و محدودیت‌های فیلدهای keyword و keywords در APIهای DataForSEO در این مقاله مرکز راهنما بیشتر بدانید"
          },
          "location_code": {
            "type": [
              "integer",
              "null"
            ],
            "description": "کد موقعیت موتور جستجو\nفیلد الزامی اگر location_name را تعیین نکنید \nاگر از این فیلد استفاده کنید، نیازی به تعیین location_name نیست\nمی‌توانید فهرست موقعیت‌های موجود موتورهای جستجو را همراه با location_code آن‌ها با ارسال یک درخواست جداگانه به https://api.dataforseo.com/v3/serp/youtube/locations دریافت کنید\nمثال:\n2840"
          },
          "language_code": {
            "type": [
              "string",
              "null"
            ],
            "description": "کد زبان موتور جستجو\nفیلد الزامی اگر language_name را تعیین نکنید\nاگر از این فیلد استفاده کنید، نیازی به تعیین language_name نیست\nمی‌توانید فهرست زبان‌های موجود موتور جستجو را همراه با language_code آن‌ها با ارسال یک درخواست جداگانه به https://api.dataforseo.com/v3/serp/youtube/languages دریافت کنید\nمثال:\nen"
          },
          "device": {
            "type": [
              "string",
              "null"
            ],
            "description": "نوع دستگاه\nفیلد اختیاری\nبازگرداندن نتایج برای نوع دستگاه خاص\nمقادیر موجود: desktop، mobile"
          },
          "block_depth": {
            "type": [
              "integer",
              "null"
            ],
            "description": "عمق تجزیه\nفیلد اختیاری\nتعداد بلوک‌های نتایج در SERP\nمقدار پیش‌فرض: 20\nحداکثر مقدار: 200\nتوجه: حساب شما برای هر SERP حاوی حداکثر 20 نتیجه صورت‌حساب می‌شود؛\nبنابراین، تعیین عمق بلوک بیش از 20 ممکن است در صورت برگرداندن بیش از 20 نتیجه توسط موتور جستجو منجر به هزینه‌های اضافی شود؛\nاگر عمق بلوک مشخص‌شده بیشتر از تعداد نتایج در پاسخ باشد، تفاوت به‌صورت خودکار به موجودی حساب شما بازگردانده می‌شود"
          },
          "location_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "نام کامل موقعیت موتور جستجو\nفیلد الزامی اگر location_code را تعیین نکنید\nاگر از این فیلد استفاده کنید، نیازی به تعیین location_code نیست\nمی‌توانید فهرست موقعیت‌های موجود موتور جستجو را همراه با location_name آن‌ها با ارسال یک درخواست جداگانه به https://api.dataforseo.com/v3/serp/youtube/locations دریافت کنید\nمثال:\nUnited States"
          },
          "language_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "نام کامل زبان موتور جستجو\nفیلد الزامی اگر language_code را تعیین نکنید\nاگر از این فیلد استفاده کنید، نیازی به تعیین language_code نیست\nمی‌توانید فهرست زبان‌های موجود موتور جستجو را همراه با language_name آن‌ها با ارسال یک درخواست جداگانه به https://api.dataforseo.com/v3/serp/youtube/languages دریافت کنید\nمثال:\nEnglish"
          },
          "os": {
            "type": [
              "string",
              "null"
            ],
            "description": "سیستم‌عامل دستگاه\nفیلد اختیاری\nاگر desktop را در فیلد device تعیین کنید، از مقادیر زیر انتخاب کنید: windows، macos\nمقدار پیش‌فرض: windows\nاگر mobile را در فیلد device تعیین کنید، از مقادیر زیر انتخاب کنید: android، ios\nمقدار پیش‌فرض: android"
          },
          "tag": {
            "type": [
              "string",
              "null"
            ],
            "description": "شناسه وظیفه تعریف‌شده توسط کاربر\nفیلد اختیاری\nمحدودیت کاراکتر 255 است\nمی‌توانید از این پارامتر برای شناسایی وظیفه و تطبیق آن با نتیجه استفاده کنید\nمقدار tag مشخص‌شده را در شیء data پاسخ پیدا می‌کنید"
          },
          "search_param": {
            "type": [
              "string",
              "null"
            ],
            "description": "پارامترهای اضافی پرس‌وجوی جستجو\nفیلد اختیاری\nمثال:\nsp=EgIQAg%253D%253D"
          }
        },
        "example": [
          {
            "language_code": "en",
            "location_code": 2840,
            "keyword": "audi"
          }
        ]
      }
    ]
  },
  "example": [
    {
      "language_code": "en",
      "location_code": 2840,
      "keyword": "audi"
    }
  ]
}
```

## Responses

### 200 — عملیات موفق

Headers:
- `X-Request-Id` (string) — شناسه درخواست برای درج هنگام تماس با پشتیبانی Felo.

**application/json**

Schema: object | null

```json
{
  "type": [
    "object",
    "null"
  ],
  "oneOf": [
    {
      "$ref": "#/components/schemas/Response36Afe1097B20_SerpYoutubeOrganicLiveAdvancedResponseInfo"
    }
  ]
}
```

### 400 — درخواست پردازش نشد. پارامترهای درخواست را بررسی کنید.

### 401 — یک کلید API معتبر Felo لازم است.

### 402 — درخواست ادامه نمی‌یابد چون یک الزام صورت‌حساب برآورده نشده است.

### 403 — حساب مجاز به انجام این عملیات نیست.

### 429 — به سقف درخواست یا هزینه رسیده‌اید.

### 502 — سرویس نتوانست درخواست را کامل کند.

### 503 — سرویس API یا صورت‌حساب موقتاً در دسترس نیست.

### 504 — سرویس هنگام پردازش درخواست به پایان مهلت رسید.

### default — پاسخ خطا؛ پاسخ‌های عبوری بالادست ممکن است از قالب‌های ارائه‌دهنده استفاده کنند

**application/json**

Schema:

```json
{}
```

## Schema definitions

### Response36Afe1097B20_BaseResponseInfo

`#/components/schemas/Response36Afe1097B20_BaseResponseInfo`

```json
{
  "properties": {
    "version": {
      "type": [
        "string",
        "null"
      ],
      "description": "نسخه فعلی API"
    },
    "status_code": {
      "type": [
        "integer",
        "null"
      ],
      "description": "کد وضعیت عمومی\nفهرست کامل کدهای پاسخ را اینجا پیدا می‌کنید"
    },
    "status_message": {
      "type": [
        "string",
        "null"
      ],
      "description": "پیام اطلاعاتی عمومی\nفهرست کامل پیام‌های اطلاعاتی عمومی را اینجا پیدا می‌کنید"
    },
    "time": {
      "type": [
        "string",
        "null"
      ],
      "description": "زمان کل اجرا، بر حسب ثانیه"
    },
    "cost": {
      "type": [
        "number",
        "null"
      ],
      "description": "هزینه کل وظایف، دلار آمریکا",
      "format": "double"
    },
    "tasks_count": {
      "type": [
        "integer",
        "null"
      ],
      "description": "تعداد وظایف در آرایه tasks",
      "format": "int64"
    },
    "tasks_error": {
      "type": [
        "integer",
        "null"
      ],
      "description": "تعداد وظایف در آرایه tasks که با خطا برگردانده شده‌اند",
      "format": "int64"
    }
  }
}
```

### Response36Afe1097B20_BaseResponseTaskInfo

`#/components/schemas/Response36Afe1097B20_BaseResponseTaskInfo`

```json
{
  "properties": {
    "id": {
      "type": [
        "string",
        "null"
      ],
      "description": "شناسه وظیفه\nشناسه یکتای وظیفه در سیستم ما در قالب UUID"
    },
    "status_code": {
      "type": [
        "integer",
        "null"
      ],
      "description": "کد وضعیت وظیفه\nتوسط DataForSEO تولید می‌شود و می‌تواند در بازه زیر باشد: 10000-60000\nفهرست کامل کدهای پاسخ را اینجا پیدا می‌کنید"
    },
    "status_message": {
      "type": [
        "string",
        "null"
      ],
      "description": "پیام اطلاعاتی وظیفه\nفهرست کامل پیام‌های اطلاعاتی عمومی را اینجا پیدا می‌کنید"
    },
    "time": {
      "type": [
        "string",
        "null"
      ],
      "description": "زمان اجرا، ثانیه"
    },
    "cost": {
      "type": [
        "number",
        "null"
      ],
      "description": "هزینه کل وظایف، دلار آمریکا",
      "format": "double"
    },
    "result_count": {
      "type": [
        "integer",
        "null"
      ],
      "description": "تعداد عناصر در آرایه result",
      "format": "int64"
    },
    "path": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": [
          "string",
          "null"
        ]
      },
      "description": "مسیر URL"
    },
    "data": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": {
        "type": [
          "object",
          "null"
        ]
      },
      "description": "همان پارامترهایی را دارد که در درخواست POST تعیین کرده‌اید"
    }
  }
}
```

### Response36Afe1097B20_BaseSerpApiYoutubeOrganicElementItem

`#/components/schemas/Response36Afe1097B20_BaseSerpApiYoutubeOrganicElementItem`

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": [
        "string",
        "null"
      ],
      "description": "نوع عنصر"
    },
    "rank_group": {
      "type": [
        "integer",
        "null"
      ],
      "description": "<em>رتبه گروه در SERP</em><br>            موقعیت در یک گروه از عناصر با مقادیر <code>type</code> یکسان<br>            موقعیت عناصر با مقادیر <code>type</code> متفاوت از <code>rank_group</code> حذف می‌شود"
    },
    "rank_absolute": {
      "type": [
        "integer",
        "null"
      ],
      "description": "<em> رتبه مطلق در SERP برای دامنه هدف</em><br>            موقعیت مطلق در میان همه عناصر SERP"
    },
    "block_rank": {
      "type": [
        "integer",
        "null"
      ],
      "description": "<em>رتبه بلوک در SERP</em><br>            موقعیت در میان همه بلوک‌های SERP"
    },
    "block_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "<em>نام بلوک در SERP</em><br>            مثال:<br>            <code>\"People also watched\"</code><br>"
    },
    "channel_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "<em>شناسه کانال</em>"
    },
    "url": {
      "type": [
        "string",
        "null"
      ],
      "description": "<em>نشانی URL کانال</em>"
    }
  },
  "additionalProperties": false,
  "discriminator": {
    "propertyName": "type",
    "mapping": {
      "youtube_channel": "#/components/schemas/Response36Afe1097B20_SerpApiYoutubeChannelElementItem",
      "youtube_video": "#/components/schemas/Response36Afe1097B20_SerpApiYoutubeVideoElementItem",
      "youtube_video_paid": "#/components/schemas/Response36Afe1097B20_SerpApiYoutubeVideoPaidElementItem",
      "youtube_playlist": "#/components/schemas/Response36Afe1097B20_SerpApiYoutubePlaylistElementItem"
    }
  }
}
```

### Response36Afe1097B20_SerpYoutubeOrganicLiveAdvancedResponseInfo

`#/components/schemas/Response36Afe1097B20_SerpYoutubeOrganicLiveAdvancedResponseInfo`

```json
{
  "type": "object",
  "allOf": [
    {
      "$ref": "#/components/schemas/Response36Afe1097B20_BaseResponseInfo"
    },
    {
      "type": "object",
      "properties": {
        "tasks": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": [
              "object",
              "null"
            ],
            "oneOf": [
              {
                "$ref": "#/components/schemas/Response36Afe1097B20_SerpYoutubeOrganicLiveAdvancedTaskInfo"
              }
            ]
          },
          "description": "آرایه وظایف"
        }
      }
    }
  ]
}
```

### Response36Afe1097B20_SerpYoutubeOrganicLiveAdvancedResultInfo

`#/components/schemas/Response36Afe1097B20_SerpYoutubeOrganicLiveAdvancedResultInfo`

```json
{
  "type": "object",
  "properties": {
    "keyword": {
      "type": [
        "string",
        "null"
      ],
      "description": "کلیدواژه دریافت‌شده در آرایه POST        کلیدواژه با کدگشایی %## برگردانده می‌شود (کاراکتر '+' به فاصله کدگشایی می‌شود)"
    },
    "se_domain": {
      "type": [
        "string",
        "null"
      ],
      "description": "دامنه موتور جستجو در آرایه POST"
    },
    "location_code": {
      "type": [
        "integer",
        "null"
      ],
      "description": "کد مکان در آرایه POST"
    },
    "language_code": {
      "type": [
        "string",
        "null"
      ],
      "description": "کد زبان در آرایه POST"
    },
    "check_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "نشانی URL مستقیم نتایج موتور جستجو        می‌توانید از آن استفاده کنید تا مطمئن شوید نتایج دقیقی ارائه کرده‌ایم"
    },
    "datetime": {
      "type": [
        "string",
        "null"
      ],
      "description": "تاریخ و زمان دریافت نتیجه            در قالب UTC: “yyyy-mm-dd hh-mm-ss +00:00”            مثال:            2019-11-15 12:57:46 +00:00"
    },
    "spell": {
      "type": [
        "object",
        "null"
      ],
      "oneOf": [
        {
          "$ref": "#/components/schemas/Response36Afe1097B20_SpellInfo"
        }
      ],
      "description": "تصحیح خودکار موتور جستجو            اگر موتور جستجو برای کلیدواژه‌ای که تصحیح شده نتایج ارائه کرده باشد، کلیدواژه تصحیح‌شده توسط موتور جستجو و نوع تصحیح خودکار را مشخص می‌کنیم"
    },
    "item_types": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": [
          "string",
          "null"
        ]
      },
      "description": "انواع نتایج جستجو در SERP            حاوی انواع نتایج جستجو (items) یافت‌شده در SERP است.            انواع آیتم ممکن:            youtube_channel, youtube_video, youtube_video_paid, youtube_playlist"
    },
    "se_results_count": {
      "type": [
        "integer",
        "null"
      ],
      "description": "تعداد کل نتایج در SERP",
      "format": "int64"
    },
    "items_count": {
      "type": [
        "integer",
        "null"
      ],
      "description": "تعداد نتایج برگشتی در آرایه items",
      "format": "int64"
    },
    "items": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": [
          "object",
          "null"
        ],
        "oneOf": [
          {
            "$ref": "#/components/schemas/Response36Afe1097B20_BaseSerpApiYoutubeOrganicElementItem"
          }
        ]
      },
      "description": "عناصر نتایج جستجوی یافت‌شده در SERP"
    }
  }
}
```

### Response36Afe1097B20_SerpYoutubeOrganicLiveAdvancedTaskInfo

`#/components/schemas/Response36Afe1097B20_SerpYoutubeOrganicLiveAdvancedTaskInfo`

```json
{
  "type": "object",
  "allOf": [
    {
      "$ref": "#/components/schemas/Response36Afe1097B20_BaseResponseTaskInfo"
    },
    {
      "type": "object",
      "properties": {
        "result": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": [
              "object",
              "null"
            ],
            "oneOf": [
              {
                "$ref": "#/components/schemas/Response36Afe1097B20_SerpYoutubeOrganicLiveAdvancedResultInfo"
              }
            ]
          },
          "description": "آرایه نتایج"
        }
      }
    }
  ]
}
```

### Response36Afe1097B20_SpellInfo

`#/components/schemas/Response36Afe1097B20_SpellInfo`

```json
{
  "properties": {
    "keyword": {
      "type": [
        "string",
        "null"
      ],
      "description": "کلیدواژه‌ای که در نتیجه تصحیح خودکار موتور جستجو به دست آمده است\n نتایج برای کلیدواژه تصحیح‌شده ارائه می‌شود"
    },
    "type": {
      "type": [
        "string",
        "null"
      ],
      "description": "نوع تصحیح خودکار\n مقادیر ممکن:\n did_you_mean, showing_results_for, no_results_found_for, including_results_for\n توجه: Yahoo و Yandex فقط از نوع تصحیح خودکار زیر پشتیبانی می‌کنند:\n including_results_for"
    }
  }
}
```
