Apple Ads Api

A TypeScript client library wrapper around the official Apple Ads API.

Features

🔒 Authentication: Full OAuth2 support with JWT for Apple Search Ads.
💾 Token Management: Built-in token storage mechanisms (File or Memory) with automatic refreshing.
🛠 Type Safety: Strong typing for all requests and responses (TypeScript).
⛓ Chaining: Convenient API for resource navigation (Campaigns -> AdGroups -> Keywords).
📊 Reports: Support for Reporting API.

Installation

npm install apple-ads-api

Usage

Client Initialization

To work with the API, you need to create a SearchAdsClient instance and provide authentication parameters.

import { SearchAdsClient, FileTokenStorage } from 'apple-ads-api';
import fs from 'fs';

// Read private key
const privateKey = fs.readFileSync('certs/private-key.pem', 'utf8');

const client = new SearchAdsClient({
  orgId: 'ORG_ID',
  auth: {
    clientId: 'SEARCHADS.00000000-0000-0000-0000-000000000000',
    teamId: 'SEARCHADS.00000000-0000-0000-0000-000000000000',
    keyId: '00000000-0000-0000-0000-000000000000',
    privateKeyPem: privateKey,
    // Optional: use file storage for token caching
    // If not specified, MemoryTokenStorage is used by default
    storage: new FileTokenStorage('./.apple-ads-token'),
  },
});

Examples

Get Campaigns

const { data: campaigns } = await client.campaigns.get({
  limit: 10,
  offset: 0,
});

console.log('Campaigns:', campaigns);

Find Campaigns with Filtering

const { data: foundCampaigns } = await client.campaigns.find({
  pagination: { limit: 10, offset: 0 },
  conditions: [
    {
      field: 'displayStatus',
      operator: 'EQUALS',
      values: ['RUNNING'],
    },
  ],
});

Working with Nested Resources

The library allows convenient access to resources related to a specific entity using chaining.

const campaignId = 123456789;

// Get Ad Groups for a specific campaign
const adGroupsResponse = await client
  .campaign(campaignId)
  .adGroups.get({ limit: 10, offset: 0 });

const adGroupId = adGroupsResponse.data[0]?.id;

if (adGroupId) {
  // Get Targeting Keywords for a specific Ad Group
  const keywords = await client
    .campaign(campaignId)
    .adGroup(adGroupId)
    .targetingKeywords.get({ limit: 10, offset: 0 });

  console.log('Keywords:', keywords.data);
}

Documentation

The project is configured to generate documentation using TypeDoc.

📄 Open local documentation (available after generation)

To generate the latest version of the documentation, run:

npm run docs

Development

Scripts

npm run build - Build the project (tsup).
npm run dev - Run build in watch mode.
npm run lint - Check code (ESLint).
npm run format - Format code (Prettier).