GatherStar Open RTB Integration

https://gatherstar.io/doc/gatherstar/docs/
Admin
GatherStar provides an RTB API that enables advertisers and publishers to integrate their platforms...
Tokens:302,982
Snippets:1,545
Trust Score:2.3
Update:10 months ago
Show doc for...
Tokens:
Raw
### Login with API Token (Partial Example)

Source: https://gatherstar.io/doc/gatherstar/docs/api-manual-php-examples/index

A partial example illustrating the initial steps for logging in with an API token. It shows the setup of the request to the /login endpoint with API token parameters.

```php
<?php

        // Include Request and Response classes

        // Login
        $url = 'https://api.gatherstar.io/v2/login';

        $params = array(
            'api_token'  => 'sample_token_2bb447abb71b69368901a....'
        );

        ...

    ?>
```

--------------------------------

### PHP Example for Click URL Handling

Source: https://gatherstar.io/doc/gatherstar/docs/third-party-adserving/index

This PHP code demonstrates how to retrieve the 'tag' and 'click_url' GET parameters from an iframe in the host page. This is crucial for server-to-server tracking and proper redirection of user clicks.

```php
<?php
$tag_tracker = isset($_GET['tag']) ? $_GET['tag'] : '';
$click_url = isset($_GET['click_url']) ? $_GET['click_url'] : '';
?>
```

--------------------------------

### JSON Examples

Source: https://gatherstar.io/doc/gatherstar/docs/open-rtb-2p5-pub-response/index

Provides JSON examples for banner ad bid responses.

```APIDOC
## JSON Examples

### Banner: JSON

```json
{
    "id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
    "seatbid": [{
        "bid": [{
            "id": "1737294d31e606ef366cbf9fd30ca409c8819978",
            "impid": "974090632",
            "price": 0.55,
            "adm": "<GatherStar_XML_OR_JSON_OR_HTML_AD_MARKUP>",
            "ext": {
                "btype": 1
            },
            "nurl": "http:\/\/network-domain.com\/not.php?zid=4068569&data=TVRZeE56STJOekl3T1h3ek9UVTROMkUyWmpObE16bGxObUZsTTJVek5UZ3lNakF6T0RBMVpUTXpaZy0tfDIwMjEtMDQtMDEgMDQ6NTM6Mjl8MTAuNDIuMC4xfFhYWHw0MXxiYmFraXJlLmNvbXw0MzI0Mzd8NDQ2MDc1fDc3NjE4Nnw0MDY4NTY5fDUwOHw0MTM5ODQ3fDQ1MzA4NDM1fDExfDJ8NDN8MHwwfDExMTF8MHwwfFVTRHxVU0R8MXwxfDIxfDMwMHgyNTB8MXxYWFh8fDE4fDJ8MXx8NTc1OTJmMzMzZjg5ODMuMDQzNTg3MTYyMjgyNDE1MDY1fDY1NThjNGRmYjM5NTdhOTk0NTg0NmMzY2MzMTExZmNjfHNpdGVkb21haW4uY29tfDB8MHwwfDB8ZDRiNWM2OTctNDFmMy00YzFjLWEzZDUtNWZkMDFiNWVmMmFhfDB8MTAyMHwwfFdJTk5FUnx8MXwwLjV8MHwwfDJ8MHwwfDB8MHwtMXwwfDB8fHx8MHwyMjIyfDMzMzN8fHx8ODd8MHwwfDEwfE9LfDUxNGE0MmQ5ZDgwZWY5OGQ4MTRmMzM2YmQyMzgwYjYw",
            "cid" : "123456",
            "crid" : "22334455"
        }]
    }]
}
```
```

--------------------------------

### Video Bid Request Example

Source: https://gatherstar.io/doc/gatherstar/docs/open-rtb-2p5-adv-request-generic/index

An example of a complete bid request for a video ad, including site, device, impression, and user details.

```APIDOC
### Request Example
```json
{
   "id": "b7da78ea-cce3-4524-a806-26ca48dd1857",
   "site": {
      "domain": "privesexopname.nl",
      "page": "https://sitedomain.com/page",
      "id": "718990",
      "keywords": "lifestyle,humour",
      "cat": [
         "IAB25-3"
      ],
      "ext": {
         "exchangecat": 508,
         "idzone": 4998567,
         "keyword": "%"
      },
      "publisher": {
         "id": "195600"
      }
   },
   "device": {
      "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36",
      "sua": {
         "architecture": "x86",
         "bitness": "64",
         "model": "Windows",
         "mobile": 0,
         "source": 2,
         "platform": {
            "brand": "Windows",
            "version": [
               "10",
               "0",
               "0"
            ]
         },
         "browsers": [
            {
               "brand": "Chromium",
               "version": [
                  "136",
                  "0",
                  "7103",
                  "93"
               ]
            },
            {
               "brand": "Microsoft Edge",
               "version": [
                  "136",
                  "0",
                  "3240",
                  "64"
               ]
            },
            {
               "brand": "Not.A\/Brand",
               "version": [
                  "99",
                  "0",
                  "0",
                  "0"
               ]
            }
         ]
      },
      "ip": "131.34.123.159",
      "geo": {
         "country": "IRL",
         "ipservice": "3"
      },
      "language": "en",
      "os": "MacOS",
      "js": 1,
      "ext": {
         "remote_addr": "131.34.123.159",
         "x_forwarded_for": ""
      }
   },
   "imp": [
      {
         "id": "568094473",
         "video": {
            "mimes": [
               "video/mp4"
            ],
            "minduration": "1",
            "maxduration": "7200",
            "ext": {
               "zone_type": "exchange_video_slider"
            },
            "protocols": "3,6",
            "linearity": "1",
            "boxingallowed": "1",
            "pos": "0"
         },
         "instl": "0",
         "ext": {
            "video_cta": "1",
            "type": "video"
         },
         "secure": "0"
      }
   ],
   "user": {
      "id": "57592f333f8983.043587162282415065"
   },
   "tmax": 300
}
```
```

--------------------------------

### Banner Bid Request Example

Source: https://gatherstar.io/doc/gatherstar/docs/open-rtb-2p5-pub-request-generic/index

Example of a complete bid request for a banner ad, including site, device, user, and extension details.

```APIDOC
## Examples

### Banner

```json
{
   "id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
   "at": 1,
   "imp": [
      {
         "id": "974090632",
         "banner": {
            "w": 300,
            "h": 250
         }
      }
   ],
   "site": {
      "id": "12345",
      "domain": "sitedomain.com",
      "cat": [
         "IAB25-3"
      ],
      "page": "https://sitedomain.com/page",
      "keywords": "lifestyle, humour"
   },
   "device": {
      "ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
      "sua": {
         "architecture": "x86",
         "bitness": "64",
         "model": "Windows",
         "mobile": 0,
         "source": 2,
         "platform": {
            "brand": "Windows",
            "version": [
               "10",
               "0",
               "0"
            ]
         },
         "browsers": [
            {
               "brand": "Chromium",
               "version": [
                  "136",
                  "0",
                  "7103",
                  "93"
               ]
            },
            {
               "brand": "Microsoft Edge",
               "version": [
                  "136",
                  "0",
                  "3240",
                  "64"
               ]
            },
            {
               "brand": "Not.A\/Brand",
               "version": [
                  "99",
                  "0",
                  "0",
                  "0"
               ]
            }
         ]
      },
      "ip": "131.34.123.159",
      "geo": {
         "country": "IRL"
      },
      "language": "en",
      "os": "Linux & UNIX",
      "js": 0,
      "ext": {
         "remote_addr": "131.34.123.159",
         "x_forwarded_for": "",
         "accept_language": "en-GB;q=0.8,pt-PT;q=0.6,en;q=0.4,en-US;q=0.2,de;q=0.2,es;q=0.2,fr;q=0.2"
      }
   },
   "user": {
      "id": "57592f333f8983.043587162282415065",
      "ext": {
         "consent": "CO9A8QHPAbnHWBcADBENBJCoAAAAAAAAAAqIHKJU9VybLh0Dq4A170B0OAEYN_r_v40zigeds-8Myd-X3DsX50M7vFy6pr4AuR4km3CBIQFkHOmcTUmw6IkVrRPsak2Mr7NKJ7PEinsbe2dYEHtfn9VTuZKZr97s___zf_-___3_75f__-3_3_vp9UAAAABA5QAkgkDYAKAQRAAJIwKhQAhAuJDoBAAUUIwtE1hASuCmYVAR-ggYAIDUBGAECDEEGIIIAAAAAkgiAkAPBAAgCIBAACAFSAhAARoAgsAJAwCAAUA0LACKAIQJCDI4KjlICAiRaKCeSMASi72MMIQSigAAAAAAAA"
      }
   },
   "ext": {
      "sub": 1221
   }
}
```

#### Banner Bid Request Structure

*   imp
    *   imp.banner
*   site
    *   site.ext
*   device
    *   device.geo
    *   device.ext
*   user
```

--------------------------------

### ADM Examples

Source: https://gatherstar.io/doc/gatherstar/docs/open-rtb-2p5-pub-response/index

Provides examples of Ad Markup (ADM) for banner ads, including HTML a-tag and general HTML formats.

```APIDOC
## ADM Examples

### Banner: HTML (a tag)

```html
<a href=\"https:\/\/sitedomain.com\/click.php?data=H4sIAAAAAAAAA0WOO27DQAxEr6LG7YLf_ZRp0qTIGVarFSzEtgJZhh2Ahw.jJjNkRc7gCXLJkkwB7Lzv3_cTv53o3ef5fIblNvVXOG9m6DKMmCgmgmLjWL.WrYe2Xg0hCAUIaKIMWVhNIGaNxWuzmaCRFxiYsDHAixTM28w0aaGZmedcMgfwaE4YiTIJKkT1TFTNTaZ55KKpliKaJTZujR1pbs3.iu_L3qf1WpfbQQSHh8sy9_v.c.nD.XFdH9tgx_O_zRedkFzmGGw5HQfntc8P40I6TalC6dgrjyipdaxjS5hkAvoFeR9FKz4BAAA-\" target=\"_blank\" ontouchstart=\"" onclick=\"var href='https:\/\/sitedomain.com\/click.php?data=H4sIAAAAAAAAA0WOO27DQAxEr6LG7YLf_ZRp0qTIGVarFSzEtgJZhh2Ahw.jJjNkRc7gCXLJkkwB7Lzv3_cTv53o3ef5fIblNvVXOG9m6DKMmCgmgmLjWL.WrYe2Xg0hCAUIaKIMWVhNIGaNxWuzmaCRFxiYsDHAixTM28w0aaGZmedcMgfwaE4YiTIJKkT1TFTNTaZ55KKpliKaJTZujR1pbs3.iu_L3qf1WpfbQQSHh8sy9_v.c.nD.XFdH9tgx_O_zRedkFzmGGw5HQfntc8P40I6TalC6dgrjyipdaxjS5hkAvoFeR9FKz4BAAA-'; this.href = href + '&clickX=' + event.clientX + '&clickY=' + event.clientY;\"><img width=\"300\" height=\"250\" src=\"https:\/\/sitedomain.com\/library\/432437\/c506e8224d74d30b946f3398fe7bf9f90a9bf5ec.jpg\" border=\"0px\" style=\"\"><\/a><img src=\"https:\/\/sitedomain.com\/cimp.php?data=TVRZeE56STJOekl3T1h3ek9UVTROMkUyWmpObE16bGxObUZsTTJVek5UZ3lNakF6T0RBMVpUTXpaZy0tfC9saWJyYXJ5LzQzMjQzNy9jNTA2ZTgyMjRkNzRkMzBiOTQ2ZjMzOThmZTdiZjlmOTBhOWJmNWVjLmpwZ3xodHRwc3wxMC40Mi4wLjF8WFhYfDQxfGJiYWtpcmUuY29tfDQzMjQzN3w0NDYwNzV8Nzc2MTg2fDQwNjg1Njl8NTA4fDQxMzk4NDd8NDUzMDg0MzV8MTF8Mnw0M3wwfDB8MTExMXw1MDB8OTB8VVNEfFVTRHwxfDF8MjF8MzAweDI1MHwxfHx8MTh8MnwxfHw1NzU5MmYzMzNmODk4My4wNDM1ODcxNjIyODI0MTUwNjV8NjU1OGM0ZGZiMzk1N2E5OTQ1ODQ2YzNjYzMxMTFmY2N8MXwwfHNpdGVkb21haW4uY29tfDB8MHwwfDEuMDJ8MXwwfGV4Y2hhbmdlX2Jhbm5lcnwwfDB8MHwtMXwwfDB8fHx8MHwyMjIyfDMzMzN8ODd8MHwwfDF8T0t8NzQwNjMzODVlMjFiYzA0NTY1M2E0NTRlNDZm_F0xY11\" width=\"1\" height=\"1\" border=\"0" />
```

### Banner: HTML

```html
<html><a href=\"http:\/\/www.examplesite.com\" target=\"_blank\"><img src =\"https:\/\/examplesite.com:8443\/image\/336x280.jpg\" \/><\/a><\/html><img src=\"https:\/\/sitedomain.com\/cimp.php?data=TVRZeE56STJPVGcyTjN3ME56SXlaV1k0T1RGbU1tVTRNR1l6WlRZMVlqSTBOamt5WW1WaVl6SmxOdy0tfHxodHRwc3wxMC40Mi4wLjF8WFhYfDQxfGJiYWtpcmUuY29tfDQzMjQzN3w0NDYwNzV8Nzc2MTg2fDQwNjg1Njl8NTA4fDQxMzk4MDl8NDUzMDgzOTd8MTF8Mnw0M3wwfDB8MTExMXwzNDAuNjg2NDgzMjh8OTB8VVNEfFVTRHwxfDF8MjF8MzAweDI1MHwxfHx8MTh8MnwxfHw1NzU5MmYzMzNmODk4My4wNDM1ODcxNjIyODI0MTUwNjV8NjU1OGM0ZGZiMzk1N2E5OTQ1ODQ2YzNjYzMxMTFmY2N8MXwwfHNpdGVkb21haW4uY29tfDB8MHwwfDAuODJ8MXwwfGV4Y2hhbmdlX2Jhbm5lcnwwfDB8MHwtMXwzMjd8MHx8fDB8MHx8MHwyMjIyfDMzM3w4N3wwfDB8MXxPS3xiMzQ4MGJmM2RiMjAzMWNiZjllZmEyMTc3NzM5MDE0NWY-\" width=\"1\" height=\"1\" border=\"0" />
```
```

--------------------------------

### Banner Ad Example

Source: https://gatherstar.io/doc/gatherstar/docs/open-rtb-2p5-pub-response-generic/index

JSON example of a bid response for a banner ad.

```APIDOC
## Banner: JSON Example

```json
{
    "id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
    "seatbid": [{
        "bid": [{
            "id": "1737294d31e606ef366cbf9fd30ca409c8819978",
            "impid": "974090632",
            "price": 0.55,
            "adm": "<GatherStar_XML_OR_JSON_OR_HTML_AD_MARKUP>",
            "ext": {
                "btype": 1
            },
            "nurl": "http:\/\/network-domain.com\/not.php?zid=4068569&data=TVRZeE56STJOekl3T1h3ek9UVTROMkUyWmpObE16bGxObUZsTTJVek5UZ3lNakF6T0RBMVpUTXpaZy0tfDIwMjEtMDQtMDEgMDQ6NTM6Mjl8MTAuNDIuMC4xfFhYWHw0MXxiYmFraXJlLmNvbXw0MzI0Mzd8NDQ2MDc1fDc3NjE4Nnw0MDY4NTY5fDUwOHw0MTM5ODQ3fDQ1MzA4NDM1fDExfDJ8NDN8MHwwfDExMTF8MHwwfFVTRHxVU0R8MXwxfDIxfDMwMHgyNTB8MXxYWFh8fDE4fDJ8MXx8NTc1OTJmMzMzZjg5ODMuMDQzNTg3MTYyMjgyNDE1MDY1fDY1NThjNGRmYjM5NTdhOTk0NTg0NmMzY2MzMTExZmNjfHNpdGVkb21haW4uY29tfDB8MHwwfDB8ZDRiNWM2OTctNDFmMy00YzFjLWEzZDUtNWZkMDFiNWVmMmFhfDB8MTAyMHwwfFdJTk5FUnx8MXwwLjV8MHwwfDJ8MHwwfDB8MHwtMXwwfDB8fHx8MHwyMjIyfDMzMzN8fHx8ODd8MHwwfDEwfE9LfDUxNGE0MmQ5ZDgwZWY5OGQ4MTRmMzM2YmQyMzgwYjYw",
            "cid" : "123456",
            "crid" : "22334455",
            "adid" : "22334455",
            "adomain" : ["wwww.advertiser.com"],
            "w" : 300,
            "h" : 250
        }]
    }]
}
```
```

--------------------------------

### Open RTB 2.5 Bid Response JSON Examples

Source: https://gatherstar.io/doc/gatherstar/docs/open-rtb-2p5-adv-response-generic/index

Provides JSON examples for Open RTB 2.5 bid responses, covering Banner, Popunder, Video, and Fullpage Interstitial ad formats. These examples illustrate the expected structure for successful bid responses.

```json
{
  "id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
  "seatbid": [
    {
      "bid": [
        {
          "id": "e3852965cc7b28d03ff3069debcc83cb6d68e753",
          "impid": "974090632",
          "price": 3.19,
          "adm": "<GatherStar_XML_OR_JSON_AD_MARKUP>",
          "ext": {
            "btype": 1
          },
          "nurl": "https://dsp.com/my_win_notification_url",
          "burl": "https://dsp.com/my_billing_notification_url",
          "cid": "5834901",
          "crid": "83232831"
        }
      ]
    }
  ]
}
```

```json
{
    "id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
    "seatbid": [
        {
            "bid": [
                {
                    "id": "54f6f08b2e323e32ea9ec4fd6944d652c842699a",
                    "impid": "974090632",
                    "price": 0.05,
                    "adm": "http://network-domain.com/fpi-render.php?data=TVRjME9UZ31",
                    "ext": {
                        "btype": 1,
                        "asset_mime_type": [
                            "video/mp4"
                        ]
                    },
                    "nurl": "http://network-domain.com/win-notification",
                    "iurl": "http://network-domain.com//your_video.mp4",
                    "cid": "7561981",
                    "crid": "195600_115116261",
                    "cat": [],
                    "adomain": [
                        "www.test.com"
                    ],
                    "w": 900,
                    "h": 1600,
                    "attr": []
                }
            ]
        }
    ],
    "cur": "EUR"
}
```

--------------------------------

### GatherStar RTB Bid Request GET URL Examples

Source: https://gatherstar.io/doc/gatherstar/docs/rtb-advertisers/exads-rtb/bid-request/exads-rtb-advertisers-request/index

Examples of GET bid requests as URLs. These examples show how to construct URLs for different ad types, including the necessary parameters and their placeholders. The 'size' parameter is conditional based on the ad type.

```url
https://rtb.{networkdomain}/rtb.php?idzone=2999625&fid=bc64cd7206ae2b2d4346f73629595660d3d117ac&id={imp_id}&url={url}&ua={user_agent}&ip={user_ip}&remote_addr={user_remote_addr_ip}&x_forwarded_for={user_x_forwarded_for_ip}&keyword={keyword}&language={language}&user_id={user_id}&sub={sub}&export=json&type=banner&size={format}
```

```url
https://rtb.{networkdomain}/rtb.php?idzone=2999625&fid=bc64cd7206ae2b2d4346f73629595660d3d117ac&id=d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa&ip=131.34.123.159&language=en&type=banner&remote_addr=131.34.123.159&ua=Mozilla/5.0%20(X11;%20Linux%20x86_64)%20AppleWebKit/537.36%20(KHTML,%20like%20Gecko)%20Chrome/66.0.3359.139%20Safari/537.36&url=https://sitedomain.com/page&user_id=57592f333f8983.043587162282415065&export=json&keyword=Lifestyle&size=300x250
```

--------------------------------

### Video Impression Example (JSON)

Source: https://gatherstar.io/doc/gatherstar/docs/open-rtb-2p5-adv-request-generic/index

This JSON snippet demonstrates the structure of a video impression within a bid request. It includes details about the site, device, and the specific video impression object with its associated parameters like MIME types, duration, protocols, and extensions.

```json
{
   "id": "b7da78ea-cce3-4524-a806-26ca48dd1857",
   "site": {
      "domain": "privesexopname.nl",
      "page": "https://sitedomain.com/page",
      "id": "718990",
      "keywords": "lifestyle,humour",
      "cat": [
         "IAB25-3"
      ],
      "ext": {
         "exchangecat": 508,
         "idzone": 4998567,
         "keyword": "%"
      },
      "publisher": {
         "id": "195600"
      }
   },
   "device": {
      "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36",
      "sua": {
         "architecture": "x86",
         "bitness": "64",
         "model": "Windows",
         "mobile": 0,
         "source": 2,
         "platform": {
            "brand": "Windows",
            "version": [
               "10",
               "0",
               "0"
            ]
         },
         "browsers": [
            {
               "brand": "Chromium",
               "version": [
                  "136",
                  "0",
                  "7103",
                  "93"
               ]
            },
            {
               "brand": "Microsoft Edge",
               "version": [
                  "136",
                  "0",
                  "3240",
                  "64"
               ]
            },
            {
               "brand": "Not.A\/Brand",
               "version": [
                  "99",
                  "0",
                  "0",
                  "0"
               ]
            }
         ]
      },
      "ip": "131.34.123.159",
      "geo": {
         "country": "IRL",
         "ipservice": "3"
      },
      "language": "en",
      "os": "MacOS",
      "js": 1,
      "ext": {
         "remote_addr": "131.34.123.159",
         "x_forwarded_for": ""
      }
   },
   "imp": [
      {
         "id": "568094473",
         "video": {
            "mimes": [
               "video/mp4"
            ],
            "minduration": "1",
            "maxduration": "7200",
            "ext": {
               "zone_type": "exchange_video_slider"
            },
            "protocols": "3,6",
            "linearity": "1",
            "boxingallowed": "1",
            "pos": "0"
         },
         "instl": "0",
         "ext": {
            "video_cta": "1",
            "type": "video"
         },
         "secure": "0"
      }
   ],
   "user": {
      "id": "57592f333f8983.043587162282415065"
   },
   "tmax": 300
}
```

--------------------------------

### GET /rtb Bid Request (URL)

Source: https://gatherstar.io/doc/gatherstar/docs/rtb-advertisers/exads-rtb/bid-request/exads-rtb-advertisers-request/index

Send bid requests using URL parameters via HTTP GET. Examples show the general structure and a populated URL for a banner request.

```APIDOC
## GET /rtb Bid Request (URL)

### Banner: URL
*General Structure*
```
https://rtb.{networkdomain}/rtb.php?idzone=2999625&fid=bc64cd7206ae2b2d4346f73629595660d3d117ac&id={imp_id}&url={url}&ua={user_agent}&ip={user_ip}&remote_addr={user_remote_addr_ip}&x_forwarded_for={user_x_forwarded_for_ip}&keyword={keyword}&language={language}&user_id={user_id}&sub={sub}&export=json&type=banner&size={format}
```

*Example*
```
https://rtb.yournetwork.com/rtb.php?idzone=2999625&fid=bc64cd7206ae2b2d4346f73629595660d3d117ac&id=d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa&ip=131.34.123.159&language=en&type=banner&remote_addr=131.34.123.159&ua=Mozilla/5.0%20(X11;%20Linux%20x86_64)%20AppleWebKit/537.36%20(KHTML,%20like%20Gecko)%20Chrome/66.0.3359.139%20Safari/537.36&url=https://sitedomain.com/page&user_id=57592f333f8983.043587162282415065&export=json&keyword=Lifestyle&size=300x250
```
```

--------------------------------

### Setting an Offset for Retrieved Records

Source: https://gatherstar.io/doc/gatherstar/docs/api-manual-global-stats/index

This example shows how to use the 'offset' parameter to define the starting position for retrieving records. The default value is 0, meaning retrieval starts from the first record.

```json
{
      "offset": 150
}
```

--------------------------------

### Get Browsers Collection - PHP

Source: https://gatherstar.io/doc/gatherstar/docs/api-manual-php-examples/index

Fetches the 'Browsers' collection from the Gatherstar API. This example demonstrates making a GET request, setting an authorization header, and processing the JSON response. It requires the Request and Response classes.

```PHP
<?php

        // Include Request and Response classes

        $url = 'https://api.gatherstar.io/v2/collections/browsers';

        // Create a new Request object
        $request = new Request($url, 'GET');

        // Set the Authorization Header retrieved from earlier Login request
        $request->setAuthorizationHeader($token->type, $token->token);

        // Send the request
        $request->send();

        // Get the Response object
        $response = $request->getResponse();

        if($response->getStatusCode() == 200) {

            $browsers = $response->getBodyDecoded();

            foreach($browsers as $browser) {

                echo $browser->id . ': ' . $browser->name . PHP_EOL;
            }
        }
        else {
            // Collection not found
            echo $response->getStatusCode() . PHP_EOL;
            echo $response->getReasonPhrase() . PHP_EOL;
            echo $response->getBody();
        }
    ?>
```

--------------------------------

### Get Advertiser Statistics by Date - PHP

Source: https://gatherstar.io/doc/gatherstar/docs/api-manual-php-examples/index

Retrieves advertiser statistics filtered by date and optionally by campaign ID. This PHP example shows how to construct a GET request with parameters and handle the JSON response. It requires the Request and Response classes.

```PHP
<?php

        // Include Request and Response classes

        $url = 'https://api.gatherstar.io/v2/statistics/a/date';

        // Specify the campaign id
        $params = array(
           'campaignid'  => 1234
        );

        $request = new Request($url, 'GET', $params);

        // Set the Authorization Header, retrieved from earlier Login request
        $request->setAuthorizationHeader($token->type, $token->token);

        // Send the request
        $request->send();

        // Get the response object
        $response = $request->getResponse();

        if($response->getStatusCode() == 200) {

            $statistics = $response->getBodyDecoded();

            foreach($statistics->result as $statistic) {

                echo $statistic->ddate . ': ' . $statistic->value . PHP_EOL;
            }
        }
        else {
            // Campaign statistics not found
            echo $response->getStatusCode() . PHP_EOL;
            echo $response->getReasonPhrase() . PHP_EOL;
            echo $response->getBody();
        }
    ?>
```

--------------------------------

### Fullpage Interstitial Publisher Example with Ad Script

Source: https://gatherstar.io/doc/gatherstar/docs/blog-creativedisplayed-event/index

This HTML example demonstrates a publisher's implementation for a Fullpage Interstitial ad. It includes a script tag to load the ad from a specified URL with various configurations, followed by a JavaScript snippet to listen for the 'creativeDisplayed' event specific to zone ID 4362883. This setup allows publishers to execute custom actions when the ad is shown.

```html
<script type="application/javascript" data-idzone="4362883"  data-ad_frequency_count="20"  data-ad_frequency_period="60"  data-type="desktop" data-browser_settings="1" data-ad_trigger_method="3" src="https://a.examplesite.com/fp-interstitial.js"></script>
<a href="https://www.exads.com">Visit exads.com!</a>
<script type="application/javascript">
    document.addEventListener('creativeDisplayed-4362883', function (e) {
        console.log("Creative shown!");
    }, false);
</script>
```

--------------------------------

### Link Code with Click URL and Tracker

Source: https://gatherstar.io/doc/gatherstar/docs/third-party-adserving/index

This example shows how to construct the anchor tag for an HTML banner on the host page, incorporating the retrieved click_url and tag_tracker. It ensures that clicks are directed through the third-party tracking server before reaching the final destination.

```html
<a target="_blank" href='<?php echo $click_url ?>https://ad.third-party-server-ad.com/click?tag=<?php echo $tag_tracker ?>' >
```

--------------------------------

### Apply Tags to Popunder Ad (Inline & Remote Script)

Source: https://gatherstar.io/doc/gatherstar/docs/using-tags/index

This example shows the recommended method for implementing popunder ads with tags 'general' and 'humour'. Tags are set within the `adConfig` object in the inline JavaScript.

```javascript
<script type="application/javascript">
(function() {

    //version 1.0.0

    var adConfig = {
    "ads_host": "a.examplesite.com",
    "syndication_host": "s.gatherstar.io",
    "idzone": 1234567,
    "popup_fallback": false,
    "popup_force": false,
    "chrome_enabled": true,
    "new_tab": false,
    "frequency_period": 720,

    "frequency_count": 1,
    "trigger_method": 3,
    "trigger_class": "",
    "only_inline": false,
    "tags": "general,humour”
};



```

--------------------------------

### GET /publisher/statistics (Example 4)

Source: https://gatherstar.io/doc/gatherstar/docs/api-manual-global-stats/index

Retrieves publisher statistics by site ID with projection. This endpoint allows fetching aggregated statistics for specific websites, with the ability to include/exclude specific data projections.

```APIDOC
## GET /publisher/statistics (Example 4)

### Description
Retrieves publisher statistics by site ID with projection. This endpoint allows fetching aggregated statistics for specific websites, with the ability to include/exclude specific data projections.

### Method
GET

### Endpoint
/publisher/statistics

### Parameters
#### Query Parameters
- **detailed** (boolean) - Optional - Specifies whether to return detailed statistics.
- **projection** (array of strings) - Optional - Array of data projections to include (e.g., "wpn", "video", "rtb").
- **filter** (object) - Optional - Filters for the statistics.
  - **date_from** (string) - Required within filter - The start date for the statistics.
  - **date_to** (string) - Required within filter - The end date for the statistics.
  - **country_iso** (array of strings) - Optional within filter - Array of country ISO codes to filter by.
- **group_by** (array of strings) - Optional - Fields to group the statistics by (e.g., "site_id").
- **order_by** (array of objects) - Optional - Criteria for ordering the results.
  - **field** (string) - Required within order_by object - The field to order by (e.g., "impressions").
  - **order** (string) - Required within order_by object - The order direction ('asc' or 'desc').
- **limit** (integer) - Optional - The maximum number of results to return.
- **offset** (integer) - Optional - The number of results to skip.

### Request Example
```json
{
  "detailed": true,
  "projection": ["wpn", "video", "rtb"],
  "filter": {
    "date_from": "2019-03-10",
    "date_to": "2019-03-11",
    "country_iso": ["USA"]
  },
  "group_by": ["site_id"],
  "order_by": [
    {
      "field": "impressions",
      "order": "desc"
    }
  ],
  "limit": 30,
  "offset": 0
}
```

### Response
#### Success Response (200)
- **request_metadata** (object) - Metadata about the request.
  - **count** (integer) - The total number of results.
  - **limit** (integer) - The limit applied to the results.
  - **offset** (integer) - The offset applied to the results.
- **result** (array of objects) - An array of publisher statistics.
  - **clicks** (integer) - Number of clicks.
  - **cpc** (float) - Cost per click.
  - **cpm** (float) - Cost per mille (thousand impressions).
  - **ctr** (float) - Click-through rate.
  - **group_by** (object) - The grouping applied to the result.
    - **site_id** (object) - Grouping by site ID.
      - **id** (integer) - The site ID.
  - **impressions** (integer) - Number of impressions.
  - **revenue** (float) - Total revenue.
  - **rtb** (object) - Real-Time Bidding statistics (if included in projection).
  - **video** (object) - Video ad statistics (if included in projection).
  - **wpn** (object) - Wireless Process Network statistics (if included in projection).

#### Response Example
```json
{
  "request_metadata": {
    "count": 1,
    "limit": 30,
    "offset": 0
  },
  "result": [
    {
      "clicks": 6158,
      "cpc": 0.032676325550836,
      "cpm": 0.067898722832777,
      "ctr": 0.20796534765961,
      "group_by": {
        "site_id": {
          "id": 12345
        }
      },
      "impressions": 2931772,
      "revenue": 198.2437763,
      "rtb": {
        "avg_cpm": 0,
        "avg_total_time": 0,
        "bid_response_ratio": 0,
        "errors": 0,
        "errors_ratio": 0,
        "no_bid": 0,
        "no_bid_ratio": 0,
        "queries": 0,
        "skipped": 0,
        "skipped_ratio": 0,
        "success": 0,
        "timeouts": 0,
        "timeouts_ratio": 0,
        "total_time": 0,
        "value": 0,
        "win_ratio": 0,
        "wins": 0
      },
      "video": {
        "cpv": 0.03733410594646,
        "impressions": 29934,
        "views": 5389,
        "vtr": 17.999866387614
      },
      "wpn": {
        "subscriptions": 0,
        "unsubscriptions": 0
      }
    }
  ]
}
```
```

--------------------------------

### Mobile Zone Object Example with Capping

Source: https://gatherstar.io/doc/gatherstar/docs/ad-plac-renderers/index

Demonstrates the 'zone' object structure for the mobile renderer, which includes an additional 'capping' property for controlling display frequency, alongside width, height, and frequency period.

```json
{
  "idzone": 9999999,
  "data": {
    "width": 300,
    "height": 250,
    "frequency_period": 30,
    "capping": 2
  }
}
```
Tokens:
Raw