Search Guide

Find datasets by keyword, concept, or both. Search looks across dataset names, descriptions, column names, and AI-enriched metadata.

Basic Search

Pass a query string and you get results ranked by relevance. By default, search uses hybrid mode, which combines traditional keyword matching with semantic similarity so you find results even when the exact words don't match.

curl "https://api.tryopendata.ai/v1/search?q=population" | jq

Search Modes

The mode parameter controls how your query is matched against datasets. There are three options:

curl "https://api.tryopendata.ai/v1/search?q=cost of living data&mode=semantic" | jq

Query Syntax

Search supports Google-style query syntax for more precise results:

• "consumer price index" - Exact phrase match (wrap in quotes)
• census -historical - Exclude a term with a minus sign
• inflation OR unemployment - Match either term

Autocomplete

The /v1/search/suggest endpoint returns dataset name suggestions for typeahead. Pass a prefix and you get back matching dataset names:

curl "https://api.tryopendata.ai/v1/search/suggest?q=con&limit=5" | jq

Filtering Results

By Provider

Filter to datasets from specific providers:

curl "https://api.tryopendata.ai/v1/search?q=employment&provider=bls" | jq

By Status

Filter by dataset ingestion status:

GET /v1/search?q=gdp&status=ready
GET /v1/search?status=error  # Find datasets with issues

By Category

Narrow results to a topic area using the category parameter:

GET /v1/search?q=wages&category=economics

Combining Filters

GET /v1/search?q=prices&provider=bls&status=ready&category=economics

Sorting Results

Control result ordering with the sort parameter:

curl "https://api.tryopendata.ai/v1/search?q=inflation&sort=recency" | jq

Time Range

When sorting by trending, queries, or downloads, you can scope the activity window with the time_range parameter:

# What's trending this week (default for trending sort)
GET /v1/search?sort=trending&time_range=week

# Most queried this month
GET /v1/search?sort=queries&time_range=month

# Options: today, week, month, year, all_time

Pagination

Use limit and offset for pagination:

# First page (default limit is 20)
GET /v1/search?q=employment

# Second page
GET /v1/search?q=employment&offset=20

# Custom page size
GET /v1/search?q=employment&limit=50&offset=100

Faceted Search

Search responses include facets for filtering. Use these to build dynamic filter UIs:

{
  "results": [...],
  "total": 150,
  "facets": {
    "provider": [
      {"value": "bls", "label": "Bureau of Labor Statistics", "count": 45},
      {"value": "census", "label": "U.S. Census Bureau", "count": 38},
      {"value": "fred", "label": "Federal Reserve (FRED)", "count": 32}
    ],
    "format": [
      {"value": "csv", "label": "CSV", "count": 100},
      {"value": "json", "label": "JSON", "count": 50}
    ],
    "category": [
      {"value": "economics", "label": "Economics", "count": 60},
      {"value": "demographics", "label": "Demographics", "count": 40}
    ],
    "temporal_granularity": [
      {"value": "monthly", "label": "Monthly", "count": 80}
    ],
    "geographic_scope": [
      {"value": "national", "label": "National", "count": 90}
    ]
  }
}

Search Tips

• Use specific terms - "consumer price index" works better than just "prices"
• Try semantic mode - If keyword search isn't finding what you want, try mode=semantic to search by concept instead of exact words
• Exclude noise - Use minus to filter out irrelevant results: census -historical
• Check facets - Use facet counts to narrow results by provider, format, or category
• Browse empty queries - Calling /v1/search with no query returns recently updated datasets, which is handy for discovering what's new

Related

• API Reference - Complete endpoint details
• Dataset Discovery - Add new datasets from URLs
• Try it - Interactive search