Apple Search Ads API - Node.js Wrapper

A comprehensive Node.js client library for the Apple Search Ads API, supporting campaigns, ad groups, keywords, reporting, and more.

Features

• ✅ Full support for Apple Search Ads API v3, v4, and v5
• ✅ OAuth authentication with automatic token management
• ✅ Certificate-based authentication (v3)
• ✅ Comprehensive endpoint coverage:
  • Campaigns management
  • Ad Groups with targeting dimensions
  • Keywords (targeting and negative)
  • Ads management
  • Reporting (campaigns, ad groups, keywords, search terms)
  • Geo search
  • Product pages
  • Budget orders
• ✅ Automatic pagination support
• ✅ CLI tool for testing and automation
• ✅ TypeScript-friendly (JSDoc annotations)
• ✅ Verbose logging option for debugging

Installation

npm install applesearchads-api-node

Configuration

Environment Variables

Create a .env file in your project root:

# Your organization ID (required)
ORG_ID=your_org_id

# API Credentials for OAuth (required for v4/v5)
CLIENT_ID=SEARCHADS.your-client-id
TEAM_ID=SEARCHADS.your-team-id
KEY_ID=your-key-id

# Certificate files
PEM_FILE=private-key.p8
KEY_FILE=private-key.p8

# Certificate directory path (optional, defaults to current directory)
CERTIFICATES_DIR_PATH=./

# API Version (v3, v4, or v5 - default: v5)
API_VERSION=v5

# Verbose logging (true/false)
VERBOSE=false

Authentication Setup

For API v4/v5 (OAuth):

1. Log in to App Store Connect
2. Navigate to Users and Access > Keys
3. Create a new API key with Apple Search Ads access
4. Download the private key (.p8 file)
5. Note your Key ID, Team ID, and Client ID

For API v3 (Certificate-based):

1. Generate a certificate and private key
2. Upload the certificate to App Store Connect
3. Configure the PEM and KEY file paths in .env

Usage

Basic Example

const SearchAdsAPI = require('applesearchads-api-node');

const api = new SearchAdsAPI();

// Get all campaigns
const campaigns = await api.getCampaigns();
console.log(campaigns);

// Get a specific campaign
const campaign = await api.getCampaign(campaignId);

// Get campaign report
const report = await api.getCampaignsReportByDate(
  '2024-01-01',
  '2024-01-31'
);

Custom Configuration

const api = new SearchAdsAPI({
  orgId: 'your_org_id',
  clientId: 'your_client_id',
  teamId: 'your_team_id',
  keyId: 'your_key_id',
  keyFile: 'path/to/private-key.p8',
  certificatesDir: './certs/',
  apiVersion: 'v5',
  verbose: true
});

API Methods

Campaigns

// Create a campaign
await api.createCampaign(adamId, countries, name, budget, dailyBudget, currency);

// Find campaigns with conditions
await api.findCampaigns(sortField, sortOrder, conditions, limit, offset);

// Get all campaigns (with auto-pagination)
await api.getCampaigns(limit, offset);

// Get a specific campaign
await api.getCampaign(campaignId);

// Update a campaign
await api.updateCampaign(campaignId, countries, name, budget, dailyBudget, currency, status, adamId);

// Delete a campaign
await api.deleteCampaign(campaignId);

Ad Groups

// Create an ad group
await api.createAdgroup(
  campaignId,
  name,
  currency,
  cpcBid,
  startTime,
  endTime,
  cpaGoal,
  automatedKeywordsOptIn,
  age,
  gender,
  deviceClass,
  dayPart,
  adminArea,
  locality,
  appDownloaders
);

// Get all ad groups for a campaign
await api.getAdgroups(campaignId, limit, offset);

// Get a specific ad group
await api.getAdgroup(campaignId, adgroupId);

// Update an ad group
await api.updateAdgroup(campaignId, adgroupId, ...options);

// Delete an ad group
await api.deleteAdgroup(campaignId, adgroupId);

Keywords

// Add targeting keywords
const keywords = [
  {
    text: 'keyword',
    matchType: 'BROAD',
    bidAmount: { amount: '1.50', currency: 'USD' }
  }
];
await api.addTargetingKeywords(campaignId, adgroupId, keywords);

// Get targeting keywords
await api.getTargetingKeywords(campaignId, adgroupId, limit, offset);

// Update targeting keywords
await api.updateTargetingKeywords(campaignId, adgroupId, keywords);

// Delete a targeting keyword
await api.deleteTargetingKeyword(campaignId, adgroupId, keywordId);

Negative Keywords

// Campaign-level negative keywords
await api.addCampaignNegativeKeywords(campaignId, keywords);
await api.getCampaignNegativeKeywords(campaignId);
await api.updateCampaignNegativeKeywords(campaignId, keywords);
await api.deleteCampaignNegativeKeywords(campaignId, keywordIds);

// Ad group-level negative keywords
await api.addAdgroupNegativeKeywords(campaignId, adgroupId, keywords);
await api.getAdgroupNegativeKeywords(campaignId, adgroupId);
await api.updateAdgroupNegativeKeywords(campaignId, adgroupId, keywords);
await api.deleteAdgroupNegativeKeywords(campaignId, adgroupId, keywordIds);

Reporting

// Campaign reports
await api.getCampaignsReportByDate(
  startDate,
  endDate,
  sortField,
  sortOrder,
  conditions,
  groupBy,
  returnRecordsWithNoMetrics,
  returnRowTotals,
  returnGrandTotals,
  granularity,
  offset,
  limit
);

// Ad group reports
await api.getAdgroupsReportByDate(campaignId, startDate, endDate, ...options);

// Keyword reports
await api.getKeywordsReportByDate(campaignId, startDate, endDate, ...options);

// Search terms reports
await api.getSearchtermsReportByDate(campaignId, startDate, endDate, ...options);

// Ad-level reports
await api.getAdLevelReportByDate(campaignId, startDate, endDate, ...options);

Geo Search

// Search for geographic locations
await api.geoSearch(word, entity, countryCode, limit, offset);

// Get admin areas for a country
await api.getAdminAreas(countryCode);

// Get localities for a country
await api.getLocalities(countryCode);

CLI Usage

The package includes a command-line interface for testing and automation.

Installation

npm install -g applesearchads-api-node

Or use locally:

npm run start -- <command>

CLI Commands

# List campaigns
searchads campaigns list

# Get a specific campaign
searchads campaigns get --id 123456

# Create a campaign
searchads campaigns create \
  --app-id 123456 \
  --countries US,GB \
  --name "My Campaign" \
  --budget 1000 \
  --daily-budget 100 \
  --currency USD

# List ad groups
searchads adgroups list --campaign-id 123456

# List keywords
searchads keywords list --campaign-id 123456 --adgroup-id 789012

# Get campaign reports
searchads reports campaigns \
  --start-date 2024-01-01 \
  --end-date 2024-01-31

# Get campaign reports with daily granularity
searchads reports campaigns \
  -g DAILY \
  --start-date 2024-01-01 \
  --end-date 2024-01-31

# Get ad group reports
searchads reports adgroups \
  --campaign-id 123456 \
  --start-date 2024-01-01 \
  --end-date 2024-01-31

# Get ad group reports with hourly granularity
searchads reports adgroups \
  --campaign-id 123456 \
  -g HOURLY \
  --start-date 2024-01-01 \
  --end-date 2024-01-01

# Geo search
searchads geo search --word "California" --country US --entity AdminArea

# Enable verbose logging
searchads -v campaigns list

Error Handling

try {
  const campaigns = await api.getCampaigns();
} catch (error) {
  console.error('API Error:', error.message);
}

The library throws descriptive errors for:

• Authentication failures
• Invalid parameters
• API rate limiting
• Network issues
• Invalid responses

Pagination

Many methods support automatic pagination when limit=0:

// Get ALL campaigns (auto-pagination)
const allCampaigns = await api.getCampaigns(0);

// Get first 100 campaigns only
const someCampaigns = await api.getCampaigns(100);

Debugging

Enable verbose logging to see all API requests and responses:

const api = new SearchAdsAPI({ verbose: true });

Or via environment variable:

VERBOSE=true

Or via CLI:

searchads -v campaigns list

API Version Support

• v5 (recommended): Latest version with all features
• v4: OAuth authentication
• v3: Certificate-based authentication (legacy)

Links

• Apple Search Ads API Documentation
• App Store Connect
• GitHub Repository

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Support

For questions or issues:

1. Check the Apple Search Ads API documentation
2. Open an issue on GitHub
3. Review existing issues and discussions

Credits

Based on the Python implementation: https://github.com/phiture/searchads_api