API Documentation | AdPeriscope

Quick Start

The AdPeriscope API is a RESTful service that allows you to access ad intelligence data programmatically. All requests must be made over HTTPS.

Base URL: https://api.adperiscope.com/v1/
All endpoints require authentication via API key.

Authentication

Include your API key in the Authorization header of every request:

Authorization: Bearer YOUR_API_KEY

You can obtain your API key from your AdPeriscope dashboard.

Endpoints

GET /ads/search
Search for ads by keyword, advertiser, or platform.

Parameters

q (string, optional): Search query (keyword, brand, etc.)
platform (string, optional): e.g. facebook, google, instagram
limit (integer, optional): Number of results (default: 20, max: 100)

Example Request

curl -X GET \"https://api.adperiscope.com/v1/ads/search?q=shoes&platform=facebook\" \\
  -H \"Authorization: Bearer YOUR_API_KEY\"

Example Response

{
  "results": [
    {
      "ad_id": "fb_123456",
      "advertiser": "ShoeBrand",
      "platform": "facebook",
      "creative_url": "https://cdn.adperiscope.com/creatives/fb_123456.jpg",
      "headline": "Step into Comfort",
      "impressions": 120000,
      "spend": 3500.50,
      "start_date": "2024-05-01",
      "end_date": "2024-05-15"
    }
    // ...
  ]
}

GET /advertisers/{advertiser_id}/ads
List all ads for a specific advertiser.

Example Request (Python)

import requests

headers = {
    \"Authorization\": \"Bearer YOUR_API_KEY\"
}
resp = requests.get(
    \"https://api.adperiscope.com/v1/advertisers/12345/ads\",
    headers=headers
)
print(resp.json())