# SpyFu

- Tool: Bubble
- Difficulty: Beginner
- Time required: 45–90 minutes
- Last updated: July 2026

## TL;DR

Connect Bubble to SpyFu using the API Connector with a simple URL parameter API key — no OAuth, no tokens, no expiry. Mark the secret_key parameter Private so Bubble sends it server-side, create separate groups for the domain and keyword API modules (they have different base URLs), and bind competitor intelligence data to Repeating Groups for client-facing competitive analysis dashboards.

## Build a Competitive Intelligence Dashboard in Bubble with SpyFu

SpyFu gives you a window into your competitors' advertising strategies — estimated monthly ad spend, their top-performing PPC keywords, historical ad copy, and organic keyword rankings. In Bubble, this data powers client-facing SEO audit tools, internal competitive analysis dashboards, and agency reporting panels where a team member types a competitor domain and instantly sees keyword overlap and spend estimates. What makes SpyFu the easiest integration in this category: authentication is a single URL parameter called secret_key. No OAuth flow, no Bearer tokens, no expiry. You get an API key from your SpyFu account settings, paste it into Bubble's API Connector as a Private URL parameter, and every GET call to SpyFu's endpoints is authenticated automatically. The only structural decision to make upfront: SpyFu's domain API and keyword API live at different base URLs (spyfu.com/apis/domain_api vs. spyfu.com/apis/keyword_api). A single Bubble API Connector group can only have one base URL, so you will create two groups — one per module. Build each call as a GET-only request (SpyFu is fully read-only), bind the domain text input to the domain parameter, and display results in a Repeating Group. A working SpyFu competitive dashboard in Bubble is realistically achievable in under 90 minutes.

## Before you start

- A SpyFu account on the Basic plan or above — API access requires a paid plan (not available on the free tier)
- Your SpyFu API key from spyfu.com → account settings → API section
- A Bubble app on any plan (all API Connector features including Private parameters are available on all Bubble plans)

## Step-by-step guide

### 1. Find Your SpyFu API Key

Log into your SpyFu account at spyfu.com. Click on your account avatar or name in the top-right corner and navigate to Account Settings. Look for an API section or API Access tab — SpyFu displays your secret key here. If you do not see an API option, your current plan does not include API access. SpyFu API access requires the Basic plan or above; check your current subscription level at spyfu.com/account/billing. Copy your secret key — it is a long alphanumeric string. Keep it secure: anyone with this key can make SpyFu API calls that consume your monthly quota. You will not need to rotate or refresh this key on a schedule (unlike OAuth tokens), but if it is ever exposed, you can regenerate it from the same account settings page. The key is the only credential you need for the entire SpyFu integration — no OAuth, no client secret, no token exchange.

**Expected result:** You have your SpyFu API secret key copied and ready to paste into Bubble's API Connector. You know your plan includes API access.

### 2. Create Two API Connector Groups for Domain API and Keyword API

In your Bubble editor, go to the Plugins tab in the left sidebar and click Add plugins. Search for API Connector (by Bubble) and install it. Click API Connector in your installed plugins list, then click Add another API. Name this first group SpyFu Domain API and set the base URL to https://www.spyfu.com/apis/domain_api. In the Shared parameters section (not Shared headers — SpyFu uses URL parameters, not headers, for auth), click Add a shared parameter. Set the key to secret_key, set the value to your copied SpyFu API key, and check the Private checkbox. This is the critical step: the Private flag on a URL parameter tells Bubble's server to append it to every outgoing request without it being visible in any browser-side network call or Bubble client-side workflow. Click Add another API again to create the second group. Name it SpyFu Keyword API and set the base URL to https://www.spyfu.com/apis/keyword_api. Add the same secret_key Private parameter to this group. The reason for two groups is that SpyFu's domain and keyword modules live at different base URLs — a single API Connector group can only have one base URL, so mixing endpoints from both modules in a single group is not reliably supported. Two groups keeps the configuration clean and avoids fragile per-call base URL overrides.

```
// API Connector group 1: SpyFu Domain API
// Base URL: https://www.spyfu.com/apis/domain_api
// Shared URL parameter (NOT header):
//   secret_key = YOUR_SPYFU_API_KEY  <-- mark Private

// API Connector group 2: SpyFu Keyword API
// Base URL: https://www.spyfu.com/apis/keyword_api
// Shared URL parameter:
//   secret_key = YOUR_SPYFU_API_KEY  <-- mark Private
```

**Expected result:** Two API Connector groups are created: 'SpyFu Domain API' at https://www.spyfu.com/apis/domain_api and 'SpyFu Keyword API' at https://www.spyfu.com/apis/keyword_api. Both have the secret_key URL parameter marked Private. You are ready to add individual calls to each group.

### 3. Add and Initialize the Domain Analysis Call

Within the SpyFu Domain API group, click Add a call. Name it Get Top Paid Keywords. Set the method to GET. Set the endpoint to /v2/domain/getTopPaidKeywords. Add a URL parameter named domain with a test value of apple.com for initialization purposes. Optionally add pageSize (value: 10) and startingRow (value: 0) for pagination control. Click Initialize call — Bubble makes a live request to SpyFu using your secret_key. When the Initialize succeeds, Bubble detects the response fields: you will see fields like keyword, searchVolume, avgAdWords, totalMonthlyClicks, and estimatedMonthlyCost. Set Use as to Data. Now add a second call named Get Domain Info. Set the method to GET and endpoint to /v2/domain/getTopCosPaidKeywordsOverlap. Add domain1 and domain2 as URL parameters (use apple.com and microsoft.com for initialization). Initialize this call too. The overlap endpoint shows keywords shared between two competing domains — one of the most requested features in competitive intelligence dashboards. Both calls inherit the secret_key parameter automatically from the group, so you do not need to add it again at the call level.

```
// GET https://www.spyfu.com/apis/domain_api/v2/domain/getTopPaidKeywords
// URL parameters (secret_key appended automatically from group):
{
  "domain": "apple.com",   // bind to Bubble Text Input in production
  "pageSize": "10",
  "startingRow": "0"
}

// Expected response:
{
  "results": [
    {
      "keyword": "macbook pro",
      "searchVolume": 450000,
      "avgAdWords": 1.8,
      "totalMonthlyClicks": 180000,
      "estimatedMonthlyCost": 850000.00,
      "position": 1
    }
  ],
  "totalAvailableResults": 487
}
```

**Expected result:** Bubble shows the detected response fields from SpyFu's domain API: keyword, searchVolume, avgAdWords, estimatedMonthlyCost, and other competitive data points. Both domain keyword and overlap calls are initialized and ready for UI binding.

### 4. Build the Competitive Analysis UI with Domain Input and Repeating Group

On your Bubble page, add a Text Input element and label it 'Enter competitor domain'. Set the placeholder to 'e.g. competitor.com'. Add a Button element labeled 'Analyze'. Add a Repeating Group below it, set its Type of content to SpyFu Domain Result (a Data Type you create with fields: keyword TEXT, searchVolume NUMBER, estimatedMonthlyCost NUMBER, totalMonthlyClicks NUMBER). Design each Repeating Group cell to show the keyword, monthly search volume, estimated monthly clicks, and estimated monthly cost. Now build the Button's workflow: add an action Make API call → Get Top Paid Keywords. In the domain parameter, bind it to the Text Input's value. Store the result in a Custom State named spyfuResults (Type: SpyFu Domain Result, or use Bubble's API response directly in the Repeating Group by setting the data source to Get Top Paid Keywords's results list). For pagination, add a Number Custom State named currentPage (initial value 0). Add a 'Load More' button whose click workflow calls Get Top Paid Keywords again with startingRow bound to currentPage × 10, then appends results. Display estimated monthly cost as a formatted currency value using Bubble's :formatted as currency operator. Do NOT trigger the API call on the text input's 'is changed' event — doing so sends a SpyFu request on every keystroke, burning your monthly API quota. The 'Analyze' button click pattern is the correct approach.

```
// Bubble Workflow: Button 'Analyze' is clicked
// Action 1: Make API call → Get Top Paid Keywords
//   domain = Text Input Domain's value
//   pageSize = 10
//   startingRow = 0

// Repeating Group data source:
// Result of step 1's results list

// Cell display:
// Keyword:         Current cell's keyword
// Monthly Searches: Current cell's searchVolume :formatted as number
// Monthly Clicks:   Current cell's totalMonthlyClicks :formatted as number
// Est. Monthly Cost: Current cell's estimatedMonthlyCost :formatted as currency

// Load More button workflow:
// Action 1: Set Custom State currentPage + 1
// Action 2: Make API call → Get Top Paid Keywords
//   startingRow = currentPage × 10
```

**Expected result:** Your Bubble competitive analysis page has a domain text input, an Analyze button, and a Repeating Group showing SpyFu keyword data. Clicking Analyze fetches real SpyFu data for the entered domain and displays it. Load More fetches the next page of results.

### 5. Add Keyword Module Calls and Complete the Dashboard

Switch to the SpyFu Keyword API group and add a call named Get Keyword Stats. Set the method to GET and endpoint to /v2/keyword/getKsData. Add URL parameters: keyword (test value: 'project management software') and countryCode (value: US). Initialize the call — Bubble detects keyword-level data including monthly US searches, CPC estimates, difficulty scores, and advertiser counts. This call lets you look up a specific keyword rather than pulling all keywords for a domain — useful for a 'keyword research' tab in your Bubble tool. Add a second Keyword API call named Get Related Keywords with endpoint /v2/keyword/getRelatedKeywords, parameter keyword. Initialize it. Now assemble a two-tab Bubble interface: Tab 1 shows domain competitive analysis (top paid keywords, estimated spend) from the Domain API calls, and Tab 2 shows keyword research (stats and related terms) from the Keyword API calls. Use Bubble's Custom States to manage which tab is active and show/hide the relevant Repeating Groups. This gives you a complete competitive intelligence tool built entirely on SpyFu data, with no backend server code, no OAuth management, and no token expiry concerns. If you want to extend this into a client-facing SaaS tool with per-user history and saved analyses, RapidDev specializes in exactly this pattern — book a free scoping call at rapidevelopers.com/contact.

```
// Keyword API group calls:

// GET https://www.spyfu.com/apis/keyword_api/v2/keyword/getKsData
// URL params:
{
  "keyword": "project management software",
  "countryCode": "US"
}

// Expected response:
{
  "results": [
    {
      "keyword": "project management software",
      "monthlySearchVolume": 60500,
      "broadCostPerClick": 12.50,
      "difficultyScore": 74,
      "totalAdvertisers": 89
    }
  ]
}

// GET https://www.spyfu.com/apis/keyword_api/v2/keyword/getRelatedKeywords
// URL params:
{
  "keyword": "project management software"
}
```

**Expected result:** Your Bubble dashboard has Domain API calls (top paid keywords, overlap analysis) and Keyword API calls (keyword stats, related keywords) both initialized and functional. Users can switch between competitive domain analysis and keyword research within the same Bubble app.

## Best practices

- Mark the secret_key URL parameter Private in the API Connector group. Even though SpyFu's auth is simpler than OAuth, your API key grants access to your SpyFu quota and account — it should never be visible in browser network requests.
- Create two separate API Connector groups for SpyFu's domain module and keyword module. Their different base URLs make a merged group unreliable and harder to maintain.
- Trigger SpyFu API calls only on explicit user actions (button clicks), not on text input changes or page loads. SpyFu's quota is shared across all calls from your account, and keystroke-triggered calls burn quota rapidly.
- Cache frequently-requested domain analyses in a Bubble Data Type with a timestamp. Before making a new SpyFu API call, check if an analysis for that domain was already saved in the last 24 hours and use the cached result if available. This reduces both API quota consumption and page load times.
- Use the pageSize and startingRow URL parameters to implement pagination in your Repeating Group rather than requesting large result sets in a single call. Start with pageSize of 10 and add a 'Load More' button that increments startingRow.
- Apply Privacy rules (Data tab → Privacy) to any Bubble Data Type that stores SpyFu analysis results, especially if the results contain competitor spend estimates that should only be visible to specific user roles.
- Check response field names by running the Initialize call before building your Repeating Group UI bindings. SpyFu's field names differ between v1 and v2 endpoints — always base your Bubble data bindings on the actual Initialize response rather than documentation examples.

## Use cases

### Client-Facing Competitive Intelligence Tool

Build a Bubble app where clients or prospects enter any domain and instantly see estimated monthly PPC spend, top paid keywords, and keyword overlap with their own domain. Position this as a free analysis tool to generate leads for an agency, or as a value-add feature inside a client portal.

Prompt example:

```
Create a Bubble page where a user enters a competitor domain, clicks 'Analyze', and sees estimated monthly ad spend, top 10 paid keywords, and estimated clicks — all fetched from SpyFu and displayed in a clean table with sortable columns.
```

### Internal Agency Competitive Research Panel

Build an internal Bubble tool where your agency team can quickly research any client's competitors — pulling top PPC keywords, spend estimates, and organic rankings from SpyFu without opening the SpyFu app itself. Store analysis results in Bubble's database for historical comparison across client campaigns.

Prompt example:

```
Build a Bubble admin panel where team members can search any domain, see SpyFu data for top PPC ads and keywords, save the result to a 'CompetitorAnalysis' Data Type linked to the relevant Client record, and compare results week over week.
```

### Keyword Overlap Dashboard for SEO/PPC Strategy

Use SpyFu's competitor overlap endpoint to show which paid keywords your target domain shares with its top competitors. Display keyword volume, estimated CPC, and monthly cost estimates in a Bubble Repeating Group, sorted by competitive pressure, to inform PPC budget decisions.

Prompt example:

```
Create a Bubble page that takes two domains (my domain + competitor), fetches keyword overlap from SpyFu, and displays shared keywords with monthly search volume, estimated CPC, and monthly spend estimate in a sortable table.
```

## Troubleshooting

### Initialize call returns 401 Unauthorized

Cause: The API key is invalid, incorrectly formatted, or the SpyFu plan does not include API access. The secret_key URL parameter being marked Private does not cause this error — it only keeps the key out of the browser.

Solution: Go to spyfu.com → account settings → API and confirm your exact API key value with no leading or trailing spaces. Verify your plan is Basic or above — the free tier does not include API access. If the key looks correct but still returns 401, regenerate the key from SpyFu's settings page and update the API Connector group's shared parameter with the new value.

### Domain API and Keyword API calls are returning 404 or unexpected data in a single API Connector group

Cause: Both the domain_api and keyword_api have different base URLs. If you put both module endpoints in one API Connector group with a single base URL, the calls to the other module will hit the wrong URL and return 404.

Solution: Create two separate API Connector groups: one with base URL https://www.spyfu.com/apis/domain_api for domain module calls, and one with base URL https://www.spyfu.com/apis/keyword_api for keyword module calls. Both groups get the same secret_key Private URL parameter. This is the correct architecture for SpyFu's multi-module API.

### SpyFu API quota is running out faster than expected

Cause: API calls are being triggered too frequently — for example, on every keystroke in a text input rather than on button click, or on every page load without caching previously fetched results.

Solution: Move all SpyFu API calls to explicit user-triggered actions (button clicks) rather than automatic triggers. If the same domain is queried repeatedly, save the results to a Bubble Data Type (e.g., 'SpyFu Analysis' with a domain field) and check if a recent analysis already exists before making a new API call. Use Bubble's Search for SpyFu Analysis with domain = input value and only call the API if no recent result is found.

### Initialize call shows 'There was an issue setting up your call'

Cause: The Initialize call could not get a successful response from SpyFu. Most commonly: the test domain value used during initialization is empty, the endpoint path has a typo, or the base URL is wrong.

Solution: For the Initialize call, make sure you have filled in a real test domain value like apple.com in the domain parameter. Verify the endpoint path starts with /v2/ (not just /domain/). Confirm the group base URL matches exactly: https://www.spyfu.com/apis/domain_api or https://www.spyfu.com/apis/keyword_api. Then click Initialize call again.

## Frequently asked questions

### Do I need a paid SpyFu plan to use the API in Bubble?

Yes. SpyFu API access requires the Basic plan or above. The free tier does not include API credentials. Check your account settings at spyfu.com — if there is no API section visible, your plan does not include API access. Upgrade to Basic or above to unlock the secret_key needed for Bubble integration.

### Why do I need two separate API Connector groups instead of one?

SpyFu's domain analysis API (spyfu.com/apis/domain_api) and keyword API (spyfu.com/apis/keyword_api) live at different base URLs. A single Bubble API Connector group can only have one base URL, so calls to both modules from one group would require overriding the base URL per call — fragile and hard to maintain. Two clean groups is the correct architecture, and both groups use the same secret_key Private URL parameter.

### Will my SpyFu API key ever expire or need to be refreshed?

SpyFu API keys do not expire automatically — unlike OAuth tokens, there is no time-based expiry. You only need to update your key if you regenerate it from SpyFu's account settings (e.g., if it was exposed). This makes SpyFu one of the lowest-maintenance integrations to operate in production.

### Why does my API quota run out faster than I expect?

SpyFu's API unit quota is shared across all calls from your account. If your Bubble app triggers calls on every text input change, on page load, or for many concurrent users, quota can exhaust quickly. Implement a button-click trigger pattern and cache results in Bubble's database to minimize redundant API calls.

### Can I show SpyFu data to end-users in a public Bubble app?

SpyFu's terms of service govern how their data can be displayed and distributed — review their terms at spyfu.com/legal before building a public-facing tool. The Bubble integration itself works for both internal and public apps; the terms of service question is a business and legal consideration, not a technical one.

---

Source: https://www.rapidevelopers.com/bubble-integrations/spyfu
© RapidDev — https://www.rapidevelopers.com/bubble-integrations/spyfu