prospeo-search-api

Prospeo Search Person API

このスキルでは、Prospeo Search Person API を使ってフィルターで見込み客を検索する方法を説明します。

使用するタイミング

次のような場合にこのスキルを使用します：

• 役職、業界、所在地、企業規模などで人物や見込み客を検索する
• Prospeo のデータベースから見込み客リストを作成する
• 州ごとのクロールが必要な、米国全域を対象とした大規模な検索を実行する

API の概要

エンドポイント： POST https://api.prospeo.io/search-person

認証： API キーを指定した X-KEY ヘッダー

レート制限：

• 1 秒あたり 2～2.5 リクエスト（1 分あたり 120～150 リクエスト）
• トークンバケット方式の実装を推奨

結果の上限：

• 1 ページあたり 25 件
• 最大 1000 ページ＝検索あたり 25,000 件
• 1 件以上の結果が返される検索リクエストにつき 1 クレジット

リクエスト形式

POST /search-person
Headers: {
  'Content-Type': 'application/json',
  'X-KEY': process.env.PROSPEO_API_KEY
}
Body: {
  page: number,        // 1-1000
  filters: ProspeoSearchFilters
}

フィルターの種類

interface ProspeoSearchFilters {
  // Location (use "State, United States #US" format)
  person_location_search?: {
    include?: string[];  // e.g., ["California, United States #US"]
    exclude?: string[];
  };

  // Job titles
  person_job_title?: {
    include?: string[];  // e.g., ["CEO", "Founder"]
    exclude?: string[];
    match_only_exact_job_titles?: boolean;
  };

  // Company size
  company_headcount_custom?: {
    min?: number;  // e.g., 11
    max?: number;  // e.g., 500
  };

  // Industry
  company_industry?: {
    include?: string[];  // e.g., ["Information Technology"]
    exclude?: string[];
  };

  // Technology stack
  company_technology?: {
    include?: string[];  // e.g., ["Salesforce", "HubSpot"]
    exclude?: string[];
  };

  // Contact requirements
  person_contact_details?: {
    email?: string[];   // ["VERIFIED"] for verified emails only
    mobile?: string[];
    operator?: string;
  };

  // Duplicate control
  person_duplicate_control?: {
    hide_people_from_all_my_lists?: boolean;
    hide_people_already_exported_before?: boolean;
  };

  // Funding (use this for "recently raised Series X" targeting)
  company_funding?: {
    // Days since last funding round. Valid values: 90, 180, 270, 365, or null (None).
    // Maps to UI dropdown "Select last funding round date".
    funding_date?: 90 | 180 | 270 | 365 | null;

    // Last funding round amount (bucketed enum range).
    // Valid bucket values: "<100K", "100K-500K", "500K-1M", "1M-5M", "5M-10M",
    // "10M-25M", "25M-50M", "50M-100M", "100M-500M", "500M+", "Max"
    last_funding?: { min?: string; max?: string } | null;

    // Total funding raised across all rounds (same bucketed enum range as last_funding).
    total_funding?: { min?: string; max?: string };

    // Funding stage checkboxes. Valid values:
    //   "Pre seed", "Seed", "Series unknown", "Series A", "Series B",
    //   "Series C", "Series D", "Series E-J",
    //   "Grant", "Angel", "Private equity", "Debt financing",
    //   "Non equity assistance", "Post IPO equity", "Undisclosed",
    //   "Post IPO debt", "Product crowdfunding", "Equity crowdfunding",
    //   "Corporate round", "Convertible note", "Secondary market",
    //   "Initial coin offering", "Post IPO secondary"
    stage?: string[];
  };

  // Company filters
  company_name?: { include?: string[]; exclude?: string[] };
  company_domain?: { include?: string[]; exclude?: string[] };
  company_revenue_custom?: { min?: number; max?: number };
  company_founding_year?: { min?: number; max?: number };
}

レスポンス形式

interface ProspeoSearchApiResponse {
  error: boolean;
  message?: string;
  results?: ProspeoSearchResult[];
  pagination?: {
    current_page: number;
    total_page: number;
    total_count: number;
    per_page: number;  // Always 25
  };
}

interface ProspeoSearchResult {
  person: {
    person_id: string;
    first_name?: string;
    last_name?: string;
    full_name?: string;
    current_job_title?: string;
    linkedin_url?: string;
    email?: string;
    email_status?: string;
    phone?: string;
    location?: {
      city?: string;
      state?: string;
      country?: string;
    };
    job_history?: Array<{
      title?: string;
      company_name?: string;
      current?: boolean;
    }>;
  };
  company?: {
    company_id?: string;
    name?: string;
    domain?: string;
    linkedin_url?: string;
    industry?: string;
    headcount?: number;
    headcount_range?: string;
    technologies?: string[];
    location?: { city?: string; state?: string; country?: string };
  };
}

州ごとのクロールパターン

米国全域を対象とする検索で結果が 25,000 件を超える場合は、州ごとに分割します：

const US_STATES_BY_SIZE = [
  'California', 'Texas', 'Florida', 'New York', 'Illinois', 'Pennsylvania',
  'Ohio', 'Georgia', 'North Carolina', 'Michigan', 'New Jersey', 'Virginia',
  'Washington', 'Arizona', 'Massachusetts', 'Tennessee', 'Indiana', 'Missouri',
  'Maryland', 'Wisconsin', 'Colorado', 'Minnesota', 'South Carolina', 'Alabama',
  'Louisiana', 'Kentucky', 'Oregon', 'Oklahoma', 'Connecticut', 'Utah', 'Iowa',
  'Nevada', 'Arkansas', 'Mississippi', 'Kansas', 'New Mexico', 'Nebraska',
  'Idaho', 'West Virginia', 'Hawaii', 'New Hampshire', 'Maine', 'Montana',
  'Rhode Island', 'Delaware', 'South Dakota', 'North Dakota', 'Alaska',
  'Vermont', 'Wyoming'
];

// Format for location filter
function formatStateLocation(state: string): string {
  return `${state}, United States #US`;
}

// Replace "United States #US" with state-specific location
function createStateFilters(baseFilters, state) {
  const stateFilters = JSON.parse(JSON.stringify(baseFilters));
  stateFilters.person_location_search.include =
    stateFilters.person_location_search.include.map(loc =>
      loc === 'United States #US' ? formatStateLocation(state) : loc
    );
  return stateFilters;
}

レート制限の実装

// Token bucket rate limiter
class TokenBucket {
  private tokens: number;
  private lastRefill: number;
  private maxTokens = 5;
  private refillRate = 2.0; // tokens per second

  async acquire(): Promise<void> {
    this.refill();
    if (this.tokens >= 1) {
      this.tokens -= 1;
      return;
    }
    const waitMs = Math.ceil(((1 - this.tokens) / this.refillRate) * 1000);
    await this.sleep(Math.max(waitMs, 500));
    this.refill();
    this.tokens -= 1;
  }
}

エラー処理

// Retry on 429 with exponential backoff
if (status === 429 && retryCount < 5) {
  const backoffMs = Math.min(2000 * Math.pow(2, retryCount), 60000);
  await sleep(backoffMs);
  return searchPeople(filters, page, retryCount + 1);
}

例：テクノロジー企業の幹部を検索する

const filters: ProspeoSearchFilters = {
  person_location_search: {
    include: ['United States #US']
  },
  person_job_title: {
    include: ['CEO', 'CTO', 'VP Engineering', 'Head of Engineering'],
    match_only_exact_job_titles: false
  },
  company_headcount_custom: {
    min: 11,
    max: 500
  },
  company_industry: {
    include: ['Information Technology', 'Software']
  },
  person_contact_details: {
    email: ['VERIFIED']
  }
};

const service = new ProspeoSearchService();
const { results, summary } = await service.searchWithStateSplitting(filters, {
  maxTotalContacts: 10000,
  maxContactsPerState: 5000
});

例：最近シリーズ A の資金調達を実施した企業

過去 180 日以内にシリーズ A の資金調達を実施した、従業員数 50～200 人の米国ソフトウェア企業で、マーケティング部門のリーダーを対象にします：

const filters: ProspeoSearchFilters = {
  person_location_search: { include: ['United States #US'] },
  person_job_title: {
    include: [
      'CMO', 'Chief Marketing Officer',
      'VP Marketing', 'Vice President Marketing',
      'Head Marketing', 'Director Marketing',
      'Growth', 'VP Growth', 'Head Growth'
    ]
  },
  company_headcount_custom: { min: 50, max: 200 },
  company_industry: {
    include: ['Software Development', 'Computer Software', 'Information Technology & Services']
  },
  company_funding: {
    funding_date: 180,
    stage: ['Series A']
  },
  person_contact_details: { email: ['VERIFIED'] }
};

より短い、または長い直近期間で絞り込むには、funding_date に 90／180／270／365 を設定します。 直近期間を無視し、現在指定されたステージにあるすべての企業を対象にするには、null を指定するか、この項目を省略します。

このリポジトリにある動作する実装

• /prospeo-full-export — これらのフィルターを使った検索およびページ分割エクスポートのスクリプト
• /list-expander scripts/pull.ts — 同じフィルターを使用した、大規模な TAM 抽出
• /list-builder — より大規模なリスト作成の一環として、両方をまとめて実行

環境変数

PROSPEO_API_KEY=your_api_key_here

---

次にすること

これはリファレンス用のスキルです。直接の次の手順はありません。/prospeo-full-export と /auto-research-public が実際の検索を構築するために使用します。

ここに案内したスキルに戻ってください。

関連スキル

• /prospeo-full-export — このリファレンスの主な利用先
• /auto-research-public — phase-prospeo.ts を介して Prospeo 検索も使用