> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# الرؤى

> اسحب مقاييس Google Ads يومية مباشرة لحملاتك أو مجموعاتك الإعلانية أو إعلاناتك، مع النقرات والتكلفة والإحالات الناجحة وقيمتها.

احصل على أداء Google Ads مباشرةً، بصف واحد لكل يوم، للحملات أو المجموعات الإعلانية أو الإعلانات التي أنشأتها عبر Ayrshare.

<ul>
  <li>تُقرأ الأرقام من Google لحظة استدعائك، وليس من نسخة تُحدَّث كل ليلة.</li>
  <li>جميع القيم النقدية بعملة حساب الإعلانات، وتُعاد في الحقل `currency` في كل صف.</li>
  <li>يستبعد Google الأيام التي لا نشاط فيها، لذا قد يُعيد نطاق زمني صفوفًا أقل من عدد أيامه.</li>
  <li>يعدّل Google تكلفة اليوم وإحالاته الناجحة لبضعة أيام بعد انتهائه، لذا قد تتغير الأيام الأخيرة بين قراءة وأخرى.</li>
  <li>لحملة Performance Max، استخدم `level=campaign` مع معرّف الحملة. لا تحتوي حملة Performance Max على إعلانات خاصة بها، لذا لا يُعيد `level=ad` أي صفوف.</li>
</ul>

## معاملات الترويسة

**Authorization** `string` *required*

[API Key](https://www.ayrshare.com/docs/apis/overview.md#authorization) of the Primary Profile.

Format: `Authorization: Bearer API_KEY`
**Profile-Key** `string`

[Profile Key](https://www.ayrshare.com/docs/apis/overview.md#profile-key-format) of a User Profile.

Format: `Profile-Key: PROFILE_KEY`

## معاملات الاستعلام

**level** `string` *required*

ما يُبلغ عنه كل صف: `campaign` (قيمة `campaignId` من الإنشاء) أو `adSet` (قيمة `adGroupId` من الإنشاء) أو `ad` (قيمة `adId` من الإنشاء).

**ids** `string` *required*

معرّفات الحملات أو المجموعات الإعلانية أو الإعلانات مفصولة بفواصل، بحد أقصى 50. يجب أن تكون جميعها في حساب إعلانات واحد.

**accountId** `string`

معرّف عميل Google Ads المكوّن من 10 أرقام، مع الشرطات أو بدونها (`123-456-7890`).

تقرأ تقارير الإعلانات والمجموعات الإعلانية حساب الإعلانات الذي تحدده هنا. وبدونه، يبحث تقرير الإعلانات في كل حسابات الإعلانات التي يصل إليها ربط Google Ads الخاص بك، بحد أقصى 25 حسابًا، ولا يعمل تقرير المجموعات الإعلانية إلا عندما يصل ربطك إلى حساب إعلانات واحد. حدّد الحساب عندما يصل ربطك إلى أكثر من 25 حساب إعلانات، أو إلى أكثر من حساب واحد في تقرير المجموعات الإعلانية. وإلا فسيُعيد الطلب `code: 101`.

**metrics** `string`

المقاييس المطلوب إرجاعها مفصولة بفواصل. احذفه للحصول عليها جميعًا. راجع [المقاييس](#metrics).

**startDate** `string` (default: قبل 30 يومًا)

اليوم الأول، بصيغة `YYYY-MM-DD`. يحتفظ Google بالأرقام اليومية لمدة 37 شهرًا؛ ويُعيد `startDate` أقدم من ذلك `code: 101`.

**endDate** `string` (default: اليوم)

اليوم الأخير، بصيغة `YYYY-MM-DD`.

## المقاييس

| المقياس | النوع | المعنى |
| - | - | - |
| `spend` | number | المبلغ المُنفَق |
| `impressions` | number | عدد مرات عرض الإعلان |
| `clicks` | number | النقرات |
| `cpm` | number أو `null` | التكلفة لكل 1,000 ظهور. `null` في يوم بلا مرات ظهور |
| `cpc` | number أو `null` | التكلفة لكل نقرة. `null` في يوم بلا نقرات |
| `ctr` | number أو `null` | نسبة النقر إلى الظهور، بالنسبة المئوية. `null` في يوم بلا مرات ظهور |
| `actions` | number | الإحالات الناجحة في Google، والتي قد تكون كسرية |
| `conversionValue` | number | قيمة تلك الإحالات الناجحة |

يظل `actions` و`conversionValue` بالقيمة `0` إلى أن يُعدّ تتبّع الإحالات الناجحة في حساب Google Ads الخاص بك. `reach` غير متاح، لأن Google لا يقدّم مدى وصول فريدًا لإعلانات البحث، و`breakdowns` غير متاحة على Google. ويُعيد طلب أيٍّ منهما `code: 101`.

## ترقيم الصفحات

تُعاد جميع الصفوف في استجابة واحدة، لذا تكون قيمة `nextCursor` دائمًا `null`.

## الأخطاء

| الرمز | متى |
| - | - |
| `101` | معامل مفقود أو غير صحيح، أو مقياس أو تقسيم غير مدعوم، أو كون `startDate` أقدم من 37 شهرًا، أو إرسال أكثر من 50 معرّفًا، أو انتماء المعرّفات إلى أكثر من حساب إعلانات واحد، أو الحاجة إلى `accountId` مع غيابه |
| `400` | حملة أو مجموعة إعلانية أو إعلان لا يخصّك، أو `accountId` ليس حساب الإعلانات المسجّل لدى Ayrshare للمعرّفات التي أرسلتها |
| `370` | تعذّر على Google إرجاع الرؤى. حاول مرة أخرى |

```bash cURL theme={"system"}
curl \
-H "Authorization: Bearer API_KEY" \
-X GET "https://api.ayrshare.com/api/ads/google/insights?level=campaign&ids=21534567890&startDate=2026-10-01&endDate=2026-10-07"
```

```javascript JavaScript theme={"system"}
const API_KEY = "API_KEY";

fetch("https://api.ayrshare.com/api/ads/google/insights?level=campaign&ids=21534567890&startDate=2026-10-01&endDate=2026-10-07", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${API_KEY}`
  }
})
  .then((res) => res.json())
  .then((json) => console.log(json))
  .catch(console.error);
```

```python Python theme={"system"}
import requests

headers = {
    "Authorization": "Bearer API_KEY",
}

r = requests.get("https://api.ayrshare.com/api/ads/google/insights?level=campaign&ids=21534567890&startDate=2026-10-01&endDate=2026-10-07", headers=headers)

print(r.json())
```

```php PHP theme={"system"}
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.ayrshare.com/api/ads/google/insights?level=campaign&ids=21534567890&startDate=2026-10-01&endDate=2026-10-07",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer API_KEY"
    ]
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error: " . $err;
} else {
    echo $response;
}
?>
```

```csharp C# theme={"system"}
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer API_KEY");

        var response = await client.GetAsync("https://api.ayrshare.com/api/ads/google/insights?level=campaign&ids=21534567890&startDate=2026-10-01&endDate=2026-10-07");
        var content = await response.Content.ReadAsStringAsync();

        Console.WriteLine(content);
    }
}
```

```go Go theme={"system"}
package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://api.ayrshare.com/api/ads/google/insights?level=campaign&ids=21534567890&startDate=2026-10-01&endDate=2026-10-07", nil)
    req.Header.Add("Authorization", "Bearer API_KEY")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
```

```java Java theme={"system"}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class GetAdInsights {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.ayrshare.com/api/ads/google/insights?level=campaign&ids=21534567890&startDate=2026-10-01&endDate=2026-10-07"))
            .header("Authorization", "Bearer API_KEY")
            .GET()
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}
```

```ruby Ruby theme={"system"}
require 'net/http'
require 'uri'

uri = URI.parse('https://api.ayrshare.com/api/ads/google/insights?level=campaign&ids=21534567890&startDate=2026-10-01&endDate=2026-10-07')

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.body
```

```json 200: Success theme={"system"}
{
  "status": "success",
  "platform": "google",
  "level": "campaign",
  "startDate": "2026-10-01",
  "endDate": "2026-10-07",
  "insights": [
    {
      "date": "2026-10-01",
      "level": "campaign",
      "id": "21534567890",
      "currency": "USD",
      "spend": 12.48,
      "impressions": 1830,
      "clicks": 41,
      "cpm": 6.82,
      "cpc": 0.3,
      "ctr": 2.2404,
      "actions": 3.5,
      "conversionValue": 140
    }
  ],
  "count": 1,
  "nextCursor": null
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.