How to Integrate a Search API - Step-by-Step Tutorial

Search API Integration: A Step-by-Step Developer Guide

Adding search capabilities to your application -- whether it's an AI chatbot, a competitive monitoring dashboard, or a content aggregator -- requires a reliable search API. This tutorial walks you through integrating a search API from scratch using SearchHive's SwiftSearch, with complete Python code you can copy and run today.

Key Takeaways

• A complete search API integration takes about 30 minutes with SearchHive's Python SDK
• SwiftSearch returns structured, parsed results -- no HTML parsing required on your end
• You can extend basic search with scraping (ScrapeForge) and analysis (DeepDive) in the same SDK
• The free tier at searchhive.dev supports 100 searches/day -- enough for development and testing

Prerequisites

Before starting, make sure you have:

• Python 3.8+ installed
• A SearchHive API key -- sign up free at searchhive.dev to get one
• Basic familiarity with Python and REST APIs

Install the SDK

pip install searchhive

That's it. The SDK includes SwiftSearch, ScrapeForge, and DeepDive -- all three APIs in one package.

Step 1: Set Up Your API Client

Create a new Python file and initialize the client:

import os
from searchhive import SwiftSearch

# Load your API key from environment variable (recommended)
API_KEY = os.environ.get("SEARCHHIVE_API_KEY", "your-api-key-here")

# Initialize the search client
search = SwiftSearch(api_key=API_KEY)

# Verify it works with a simple query
results = search.search(query="SearchHive API", num_results=3)
print(f"Found {len(results.organic)} results")
for r in results.organic:
    print(f"  - {r.title}")

Tip: Store your API key in an environment variable, never hardcode it in source code. Add it to your .env file:

SEARCHHIVE_API_KEY=sh_live_xxxxxxxxxxxxx

Step 2: Perform a Basic Search

SwiftSearch returns parsed, structured results -- titles, URLs, descriptions, and metadata ready to use:

from searchhive import SwiftSearch

search = SwiftSearch(api_key=API_KEY)

results = search.search(
    query="best Python web frameworks 2025",
    num_results=10
)

# Access organic results
for r in results.organic:
    print(f"Title:   {r.title}")
    print(f"URL:     {r.url}")
    print(f"Snippet: {r.description}")
    print(f"Position: {r.position}")
    print("---")

No HTML parsing. No regex tester. The SDK handles all of that and returns clean Python objects.

Step 3: Add Geo-Targeting

Localized search results are critical for many applications -- local business tools, market research, competitive analysis:

from searchhive import SwiftSearch

search = SwiftSearch(api_key=API_KEY)

# Search from a specific country
results = search.search(
    query="best coffee shops",
    country="us",
    language="en",
    num_results=10
)

# Search from a specific city (where supported)
results_local = search.search(
    query="plumber near me",
    country="us",
    location="New York, NY",
    num_results=10
)

for r in results_local.organic[:5]:
    print(f"{r.title} - {r.url}")

SwiftSearch supports 190+ countries and major cities, so you can get location-specific results for global applications.

Step 4: Filter by Freshness

For news monitoring, trend tracking, or any time-sensitive application:

from searchhive import SwiftSearch

search = SwiftSearch(api_key=API_KEY)

# Only results from the past 24 hours
recent = search.search(
    query="artificial intelligence breakthrough",
    freshness="day",
    num_results=10
)

# Past week
week = search.search(
    query="startup funding rounds",
    freshness="week",
    num_results=10
)

# Past month
month = search.search(
    query="Python 4.0 release date",
    freshness="month",
    num_results=10
)

print(f"Today: {len(recent.organic)} results")
print(f"This week: {len(week.organic)} results")
print(f"This month: {len(month.organic)} results")

Step 5: Add Web Scraping to Get Full Content

SERP snippets only tell you so much. To get the actual page content behind each result, use ScrapeForge:

from searchhive import SwiftSearch, ScrapeForge

search = SwiftSearch(api_key=API_KEY)
scraper = ScrapeForge(api_key=API_KEY)

# Step 1: Find relevant pages
results = search.search(
    query="machine learning tutorial beginners",
    num_results=5
)

# Step 2: Scrape the full content
urls = [r.url for r in results.organic]
pages = scraper.scrape_urls(urls=urls, format="markdown")

# Step 3: Use the content
for page in pages:
    print(f"URL: {page.url}")
    print(f"Content: {len(page.content)} characters")
    print(f"Preview: {page.content[:200]}...")
    print("---")

The format="markdown" parameter converts pages to clean markdown -- perfect for feeding into LLMs or displaying in your application.

Step 6: Build a Content Analysis Pipeline

Combine all three SearchHive APIs for a complete search-and-analyze workflow:

from searchhive import SwiftSearch, ScrapeForge, DeepDive

# Initialize all three clients with one API key
search = SwiftSearch(api_key=API_KEY)
scraper = ScrapeForge(api_key=API_KEY)
analyzer = DeepDive(api_key=API_KEY)

def research_topic(query, num_results=5):
    # 1. Find relevant pages
    results = search.search(query=query, num_results=num_results)
    
    # 2. Get full content
    pages = scraper.scrape_urls(
        urls=[r.url for r in results.organic],
        format="markdown"
    )
    
    # 3. Analyze each page
    analyses = []
    for page in pages:
        analysis = analyzer.analyze(
            text=page.content,
            extract_entities=True,
            summarize=True,
            detect_sentiment=True
        )
        analyses.append({
            "url": page.url,
            "summary": analysis.summary,
            "sentiment": analysis.sentiment,
            "entities": [e["name"] for e in analysis.entities]
        })
    
    return analyses

# Use it
results = research_topic("RAG pipeline best practices 2025")
for r in results:
    print(f"[{r['sentiment']}] {r['url']}")
    print(f"  Summary: {r['summary'][:150]}...")
    print(f"  Entities: {', '.join(r['entities'][:5])}")

Step 7: Add Error Handling and Rate Limiting

Production code needs proper error handling:

from searchhive import SwiftSearch, SearchHiveError, RateLimitError
import time

search = SwiftSearch(api_key=API_KEY)

def safe_search(query, max_retries=3):
    for attempt in range(max_retries):
        try:
            results = search.search(query=query, num_results=10)
            return {
                "results": results.organic,
                "total": len(results.organic),
                "query": query
            }
        except RateLimitError:
            wait_time = 2 ** attempt
            time.sleep(wait_time)
        except SearchHiveError as e:
            raise
    raise Exception(f"Failed after {max_retries} retries")

data = safe_search("search API comparison")
print(f"Got {data['total']} results")

Step 8: Integrate into a Web Application

Here's a minimal FastAPI endpoint:

from fastapi import FastAPI, HTTPException
from searchhive import SwiftSearch, ScrapeForge, DeepDive
import os

app = FastAPI(title="Search API Demo")
API_KEY = os.environ["SEARCHHIVE_API_KEY"]

search = SwiftSearch(api_key=API_KEY)
scraper = ScrapeForge(api_key=API_KEY)
analyzer = DeepDive(api_key=API_KEY)

@app.get("/search")
async def search_endpoint(q: str, limit: int = 5):
    results = search.search(query=q, num_results=limit)
    return {
        "query": q,
        "results": [
            {"title": r.title, "url": r.url, "description": r.description}
            for r in results.organic
        ]
    }

@app.get("/research")
async def research_endpoint(q: str):
    results = search.search(query=q, num_results=5)
    pages = scraper.scrape_urls(
        urls=[r.url for r in results.organic],
        format="markdown"
    )
    analyses = []
    for page in pages:
        a = analyzer.analyze(
            text=page.content,
            summarize=True,
            detect_sentiment=True
        )
        analyses.append({
            "url": page.url,
            "summary": a.summary,
            "sentiment": a.sentiment
        })
    return {"query": q, "analyses": analyses}

Run with uvicorn main:app --reload and you have a search API in under 50 lines of code.

Common Issues and Fixes

Next Steps

Now that you have a working search API integration:

1. Add caching -- cache search results to reduce API calls and improve response times
2. Build pagination -- implement cursor-based pagination for large result sets
3. Add filters -- filter by date range, domain, or content type
4. Monitor usage -- track API calls and set up alerts for approaching limits
5. Explore ScrapeForge -- add full page scraping for deeper content access
6. Try DeepDive -- add AI-powered analysis to your search results

Read the SearchHive documentation for all available parameters and advanced features. The free tier gives you everything you need to build and ship.

See also: /blog/complete-guide-to-ai-agent-web-scraping | /blog/complete-guide-to-rag-pipeline-architecture