Search API

The Search API allows you to programmatically search podcast transcriptions using the same powerful search engine that powers Audioscrape. Search for specific terms, phrases, or topics across our entire database of transcribed podcast content.

Search Transcriptions ¶

Search podcast transcriptions for specific terms or phrases.

bash

GET /api/search

curl "https://www.audioscrape.com/api/search?q=machine%20learning%20AND%20neural%20networks&limit=2" \
     -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "results": [
    {
      "podcast": {
        "id": 42,
        "title": "Tech Talk Weekly",
        "slug": "tech-talk-weekly"
      },
      "episode": {
        "id": 789,
        "title": "The Future of AI",
        "slug": "the-future-of-ai",
        "pub_date": "2023-11-15T08:30:00Z"
      },
      "matches": [
        {
          "field_type": "transcription",
          "text": "The advancements in machine learning and neural networks over the past decade have been remarkable.",
          "segment_id": "125.4"
        }
      ]
    },
    {
      "podcast": {
        "id": 86,
        "title": "Data Science Digest",
        "slug": "data-science-digest"
      },
      "episode": {
        "id": 512,
        "title": "ML Models Explained",
        "slug": "ml-models-explained",
        "pub_date": "2023-10-22T14:15:00Z"
      },
      "matches": [
        {
          "field_type": "transcription",
          "text": "Neural networks are a type of machine learning model that can learn complex patterns.",
          "segment_id": "347.2"
        }
      ]
    }
  ],
  "total": 58,
  "limit": 2,
  "offset": 0
}

Parameters

Parameter	Type	Required	Description
q	string	Yes	The search query to find in transcriptions
limit	integer	No	Maximum number of results to return (default: 20)
offset	integer	No	Number of results to skip for pagination (default: 0)

Advanced Query Syntax ¶

Our search API supports advanced query syntax for more precise searches:

Syntax	Description	Example
`"phrase"`	Exact phrase matching	`"machine learning"` - matches the exact phrase "machine learning"
`AND`	Both terms must be present	`AI AND ethics` - finds content with both "AI" and "ethics"
`OR`	Either term can be present	`python OR javascript` - finds content with either term
`NOT` or `-`	Excludes content with the term	`AI NOT chatgpt` or `AI -chatgpt` - finds AI content without ChatGPT
`,` (comma)	Works like OR operator	`python, javascript` - same as "python OR javascript"
`&` (ampersand)	Works like AND operator	`machine & learning` - same as "machine AND learning"
`term*`	Wildcard search (prefix matching)	`program*` - matches program, programming, programmer, etc.
Compound words	Words with hyphens work as expected	`real-time` - matches hyphenated terms
Apostrophes	Contractions and possessives work as expected	`don't` or `Sam's` - matches with apostrophes

Search Tips

You can combine these operators for complex searches. For example: "neural networks" AND (python OR tensorflow) NOT "image recognition" would find content about neural networks with Python or TensorFlow, but excluding image recognition.

Response Structure ¶

The search API returns a structured response with the following fields:

Field	Type	Description
results	array	Array of search result objects
total	integer	Total number of matching results
limit	integer	Maximum number of results returned in this response
offset	integer	Number of results skipped for pagination

Result Object

Each result object contains detailed information about a matching transcription segment:

Field	Type	Description
podcast	object	Information about the podcast containing the match
episode	object	Information about the specific episode containing the match
matches	array	Array of text passages that match the search query

Usage Limits ¶

The Search API has usage limits based on your subscription plan. Each search query counts as one API call against your monthly quota.

Plan	API Calls per Month	Rate Limit
Professional (Researchers)	1,000	10 calls per minute
Growth (Podcasters)	5,000	20 calls per minute
Professional (Podcasters)	20,000	60 calls per minute
Enterprise	Custom	Custom

For detailed information about our plans and pricing, please visit our pricing page.

Best Practices ¶

Use specific search terms for better results. General terms may return too many matches.

Use quoted phrases for exact matching when searching for specific expressions or names.

Implement caching for frequent searches to reduce API calls and improve performance.

Use pagination (limit and offset parameters) to navigate through large result sets.

Use the NOT operator (-) to exclude irrelevant content and narrow down results.

Consider combining the Search API with the Notifications API for ongoing monitoring of specific topics.

Error Handling ¶

The API returns standard HTTP status codes and JSON error responses:

Status Code	Description	Example
400	Bad Request - Invalid parameters	Missing required 'q' parameter
401	Unauthorized - Invalid API key	Missing or invalid Authentication header
429	Too Many Requests - Rate limit exceeded	Exceeded plan's calls per minute limit
500	Internal Server Error	Unexpected server error

Example Error Response:

{
  "code": "BAD_REQUEST",
  "message": "Missing required query parameter 'q'"
}