Semantic Search - Adjacent News API

Advanced AI-Powered Market Search

This endpoint provides state-of-the-art semantic search capabilities that revolutionize how you discover and explore prediction markets. Unlike traditional keyword-based search, our AI-powered system understands the meaning and context of your queries to deliver highly relevant results, even when markets use different terminology than your search terms.

How Semantic Search Works

🧠 The Technology Behind It

Our semantic search system leverages advanced machine learning to understand the true meaning of your queries:

Vector Embeddings: Your search query is converted into a high-dimensional vector that captures its semantic meaning
Cloudflare Vectorize: We use Cloudflare’s powerful vector database to store and search through embeddings of all markets
Similarity Matching: The system finds markets with embeddings most similar to your query vector
Intelligent Ranking: Results are ranked by semantic similarity, recency, and market activity
Fallback Protection: If vector search fails, automatic fallback to sophisticated text search ensures you always get results

🎯 Why Semantic Search Matters

Traditional search would miss many relevant markets. Our semantic search finds connections that keyword search cannot: Example Queries and Matches:

“Economic downturn” → Markets about “recession,” “GDP decline,” “unemployment rise”
“Space exploration” → Markets about “Mars missions,” “SpaceX launches,” “NASA programs”
“Tech regulation” → Markets about “antitrust,” “data privacy laws,” “social media oversight”
“Climate action” → Markets about “carbon tax,” “renewable energy,” “Paris agreement”

API Reference

Query Parameters

string

required

Your search query in natural language.Examples:

"Will Trump win in 2024?"
"future of artificial intelligence"
"climate change impacts"
"economic indicators recession"

Tips:

Use natural language - ask questions as you would to a person
Include specific entities (names, places, organizations)
Context matters - “Apple stock” vs “Apple fruit”

limit

integer

default:10

Maximum number of markets to return.

Range: 1-100 markets
Default: 10 markets
Performance: Larger limits may increase response time
Tip: Start with 10-20 for most use cases

include_context

boolean

default:false

Include additional context and relevance information.When enabled, provides:

Relevance scores (0.0-1.0)
Search method used (vector/fallback)
Query processing details
Performance metrics

platform

string

Filter results to specific platforms.Supported platforms:

kalshi - Kalshi markets
polymarket - Polymarket
manifold - Manifold Markets
metaculus - Metaculus

Format: "kalshi,polymarket" for multiple platforms

Response Format

Standard Response

{
  "data": [
    {
      "market_id": "polymarket_will-us-inflation-exceed-3-percent-in-2025",
      "platform": "polymarket",
      "question": "Will US inflation exceed 3% in 2025?",
      "description": "This market resolves to 'Yes' if the US Consumer Price Index...",
      "probability": 0.67,
      "volume": 125000,
      "liquidity": 8500,
      "status": "active",
      "end_date": "2025-12-31T23:59:59Z",
      "category": "economics",
      "tags": ["inflation", "economics", "CPI", "federal-reserve"]
    }
    // ... more markets
  ],
  "meta": {
    "query": "future inflation rates",
    "limit": 10,
    "total_results": 45,
    "search_time": "0.12s"
  }
}

Enhanced Response (with context)

{
  "data": [
    {
      "market_id": "polymarket_will-us-inflation-exceed-3-percent-in-2025",
      "platform": "polymarket", 
      "question": "Will US inflation exceed 3% in 2025?",
      "probability": 0.67,
      "volume": 125000,
      // ... other market fields
      "relevance_score": 0.94,
      "match_explanation": "High semantic similarity to 'inflation rates' query"
    }
  ],
  "meta": {
    "query": "future inflation rates",
    "query_processed": "inflation economic indicators future projections",
    "search_method": "vector",
    "total_results": 45,
    "search_time": "0.12s",
    "vector_similarity_threshold": 0.75
  }
}

Search Capabilities & Examples

1. Conceptual Searches

Find markets related to broad concepts:

# Economic concepts
curl "https://api.data.adj.news/api/search/query?q=economic%20recession%20indicators"

# Social phenomena  
curl "https://api.data.adj.news/api/search/query?q=social%20media%20influence%20on%20politics"

# Technology trends
curl "https://api.data.adj.news/api/search/query?q=artificial%20intelligence%20job%20displacement"

2. Question-Based Searches

Search using natural questions:

# Direct questions
curl "https://api.data.adj.news/api/search/query?q=Will%20Bitcoin%20reach%20100k%20in%202025?"

# Hypothetical scenarios
curl "https://api.data.adj.news/api/search/query?q=What%20if%20there%27s%20another%20pandemic?"

# Comparative questions
curl "https://api.data.adj.news/api/search/query?q=Which%20party%20will%20control%20Congress?"

3. Topic-Based Discovery

Explore markets around specific topics:

# Broad topics
curl "https://api.data.adj.news/api/search/query?q=climate%20change%20predictions&limit=20"

# Specific events
curl "https://api.data.adj.news/api/search/query?q=World%20Cup%202026%20outcomes"

# Emerging trends
curl "https://api.data.adj.news/api/search/query?q=quantum%20computing%20breakthroughs"

4. Entity-Focused Searches

Find markets related to specific people, companies, or organizations:

# Political figures
curl "https://api.data.adj.news/api/search/query?q=Donald%20Trump%20political%20future"

# Companies
curl "https://api.data.adj.news/api/search/query?q=Tesla%20stock%20performance%20predictions"

# Organizations
curl "https://api.data.adj.news/api/search/query?q=Federal%20Reserve%20policy%20decisions"

Advanced Search Techniques

# Platform-specific search
curl "https://api.data.adj.news/api/search/query?q=presidential%20election&platform=kalshi,polymarket"

# Category filtering
curl "https://api.data.adj.news/api/search/query?q=AI%20developments&category=technology&limit=15"

# Include detailed context
curl "https://api.data.adj.news/api/search/query?q=cryptocurrency%20regulation&include_context=true"

Multi-dimensional Queries

# Time-sensitive searches
curl "https://api.data.adj.news/api/search/query?q=2024%20election%20swing%20states%20outcomes"

# Geographic focus
curl "https://api.data.adj.news/api/search/query?q=European%20Union%20policy%20changes"

# Industry-specific
curl "https://api.data.adj.news/api/search/query?q=pharmaceutical%20drug%20approval%20timeline"

Fallback Text Search

When Fallback Activates

If vector search is unavailable or returns insufficient results, the system automatically uses advanced text search: Fallback triggers:

Vector search service temporarily unavailable
Query returns fewer than 3 results
Very new markets not yet indexed for vector search

How Text Search Works

Query Processing: Breaks down your query into meaningful keywords
Fuzzy Matching: Handles typos and variations in spelling
Relevance Ranking: Scores results based on keyword frequency, recency, and market activity
Context Awareness: Considers market descriptions, rules, and tags

Fallback Response

{
  "meta": {
    "search_method": "fallback",
    "fallback_reason": "Insufficient vector results",
    "query_keywords": ["artificial", "intelligence", "regulation", "policy"],
    "text_search_score": 0.87
  }
}

Use Cases & Applications

1. Market Discovery Platforms

Build intuitive search interfaces for market exploration:

# Auto-suggest implementation
curl "https://api.data.adj.news/api/search/query?q=climate&limit=5"

# Category browsing
curl "https://api.data.adj.news/api/search/query?q=sports%20championships&category=sports"

2. Research & Analysis Tools

Power analytical applications with semantic search:

# Thematic analysis
curl "https://api.data.adj.news/api/search/query?q=geopolitical%20tensions%20impact&limit=50"

# Trend identification  
curl "https://api.data.adj.news/api/search/query?q=emerging%20technology%20adoption"

3. Personalized Recommendations

Create recommendation systems based on user interests:

# Interest-based recommendations
curl "https://api.data.adj.news/api/search/query?q=renewable%20energy%20transition"

# Similar market discovery
curl "https://api.data.adj.news/api/search/query?q=electric%20vehicle%20market%20share"

4. Content Curation

Curate markets for newsletters, dashboards, or feeds:

# Weekly highlights
curl "https://api.data.adj.news/api/search/query?q=major%20political%20developments&limit=10"

# Topic-focused feeds
curl "https://api.data.adj.news/api/search/query?q=space%20exploration%20milestones"

Performance & Optimization

Response Time Optimization

Typical Performance:

Vector Search: 0.1-0.5 seconds
Text Fallback: 0.2-0.8 seconds
Factors: Query complexity, result count, filtering

Optimization Tips:

Use smaller limit values for faster responses
Cache frequently searched terms
Implement request debouncing for auto-suggest
Consider pagination for large result sets

Caching Strategy

// Example caching approach
const cacheKey = `search:${query}:${limit}:${platform}`;
const cacheDuration = 300; // 5 minutes

// Cache popular searches longer
if (isPopularQuery(query)) {
  cacheDuration = 900; // 15 minutes
}

Search Quality Tips

Query Construction:
- Be specific but not overly restrictive
- Include context for ambiguous terms
- Use natural language over keyword stuffing
Result Processing:
- Consider relevance scores when available
- Implement result deduplication if needed
- Combine with other filtering for precision

Error Handling & Troubleshooting

Common Issues

No Results Found

{
  "data": [],
  "meta": {
    "query": "very specific niche topic",
    "total_results": 0,
    "suggestion": "Try broader search terms or remove filters"
  }
}

Solutions:

Broaden your search terms
Remove platform or category filters
Try related concepts or synonyms
Check for typos in your query

Poor Result Quality

Symptoms: Irrelevant or low-quality matches Solutions:

Be more specific in your query
Use include_context=true to understand matching
Add context words to clarify meaning
Consider using entity names or specific terminology

Slow Response Times

Causes: Complex queries, large result sets, system load Solutions:

Reduce the limit parameter
Simplify your query
Implement caching
Use pagination for large result sets

Error Responses

{
  "error": {
    "code": "INVALID_QUERY",
    "message": "Query parameter 'q' is required",
    "details": {
      "parameter": "q",
      "received": null
    }
  }
}

Best Practices

Search Query Design

Natural Language: Write queries as you would ask a person
Specificity Balance: Specific enough to be relevant, broad enough to find results
Context Inclusion: Add context for ambiguous terms
Entity Names: Include specific names of people, places, organizations

Integration Patterns

Auto-suggest: Implement debounced search with small limits
Pagination: Use limit/offset for large result sets
Caching: Cache popular searches to improve performance
Fallback Handling: Always handle both vector and text search responses

User Experience

Loading States: Show search progress for longer queries
Result Highlighting: Highlight matching terms in results
Search Suggestions: Offer query refinement suggestions
Error Recovery: Provide helpful error messages and suggestions

Questions or Issues? Contact our team at lucas@adj.news with:

Example queries that aren’t working as expected
Performance concerns or optimization questions
Integration support needs

Authorizations

Authorization

string

header

required

Enter your API key as the bearer token

Query Parameters

string

required

Search query text

limit

integer

default:5

Number of results to return, default is 5 results

include_context

boolean

default:false

Include context and relevance info

Response

200

application/json

Search results

The response is of type object.

Markets API

Search API

Analytics API

News API

Trade API

​Advanced AI-Powered Market Search

​How Semantic Search Works

​🧠 The Technology Behind It

​🎯 Why Semantic Search Matters

​API Reference

​Query Parameters

​Response Format

​Standard Response

​Enhanced Response (with context)

​Search Capabilities & Examples

​1. Conceptual Searches

​2. Question-Based Searches

​3. Topic-Based Discovery

​4. Entity-Focused Searches

​Advanced Search Techniques

​Filtering and Refinement

​Multi-dimensional Queries

​Fallback Text Search

​When Fallback Activates

​How Text Search Works

​Fallback Response

​Use Cases & Applications

​1. Market Discovery Platforms

​2. Research & Analysis Tools

​3. Personalized Recommendations

​4. Content Curation

​Performance & Optimization

​Response Time Optimization

​Caching Strategy

​Search Quality Tips

​Error Handling & Troubleshooting

​Common Issues

​No Results Found

​Poor Result Quality

​Slow Response Times

​Error Responses

​Best Practices

​Search Query Design

​Integration Patterns

​User Experience

Authorizations

Query Parameters

Response

Advanced AI-Powered Market Search

How Semantic Search Works

🧠 The Technology Behind It

🎯 Why Semantic Search Matters

API Reference

Query Parameters

Response Format

Standard Response

Enhanced Response (with context)

Search Capabilities & Examples

1. Conceptual Searches

2. Question-Based Searches

3. Topic-Based Discovery

4. Entity-Focused Searches

Advanced Search Techniques

Filtering and Refinement

Multi-dimensional Queries

Fallback Text Search

When Fallback Activates

How Text Search Works

Fallback Response

Use Cases & Applications

1. Market Discovery Platforms

2. Research & Analysis Tools

3. Personalized Recommendations

4. Content Curation

Performance & Optimization

Response Time Optimization

Caching Strategy

Search Quality Tips

Error Handling & Troubleshooting

Common Issues

No Results Found

Poor Result Quality

Slow Response Times

Error Responses

Best Practices

Search Query Design

Integration Patterns

User Experience