Skip to content

OWID Search API

Semantic search API for Our World in Data indicators using embeddings and vector similarity.

This API enables you to find relevant indicators using natural language queries. Results are ranked by semantic similarity to your query, making it easy to discover indicators even if you don't know the exact terminology.

For searching charts and articles by title or content, see our Search API.

Try it out

You can try out the API interactively at https://search.owid.io/docs

API Information

Version: 0.1.0

Base URL: https://search.owid.io — Production server

GET /health

Health

Responses

✅ 200 - Successful Response

Content-Type: application/json

GET /indicators

Search Indicators Semantic

Search for indicators using semantic similarity.

This endpoint performs semantic search on OWID indicators using preloaded embeddings and returns the most relevant results.

Parameters

Parameter Type Required Description
query any Search query
q any Search query (alias for 'query')
limit integer Limit the number of results
default: 10
min_popularity any Minimum popularity score (0-1) to filter results

Responses

✅ 200 - Successful response with search results

Content-Type: application/json

Example: GDP search

Request: GET https://search.owid.io/indicators?q=gdp

Code samples:

curl "https://search.owid.io/indicators?q=gdp"

import requests

params = {
    "q": "gdp"
}
response = requests.get("https://search.owid.io/indicators", params=params)
data = response.json()

const params = new URLSearchParams({ q: "gdp" });
const response = await fetch(`https://search.owid.io/indicators?${params}`);
const data = await response.json();

let response = reqwest::get("https://search.owid.io/indicators")
        .query(&[("q", "gdp")])
    .await?
    .json::<serde_json::Value>()
    .await?;

Response schema: SemanticSearchResponse

{
  "results": [
    {
      "title": "GDP per capita, PPP (constant 2017 international $)",
      "indicator_id": 123456,
      "snippet": "GDP per capita based on purchasing power parity (PPP)...",
      "score": 0.985,
      "metadata": {
        "chart_count": 12,
        "catalog_path": "grapher/worldbank_wdi/2023-05-29/wdi/ny_gdp_pcap_pp_kd",
        "parquet_url": "https://catalog.ourworldindata.org/grapher/worldbank_wdi/2023-05-29/wdi.parquet",
        "run_sql_template": "SELECT country, year, ny_gdp_pcap_pp_kd FROM 'https://catalog.ourworldindata.org/grapher/worldbank_wdi/2023-05-29/wdi.parquet' WHERE country = 'France' LIMIT 100",
        "column": "ny_gdp_pcap_pp_kd",
        "unit": "constant 2017 international $"
      },
      "catalog_path": "grapher/worldbank_wdi/2023-05-29/wdi/ny_gdp_pcap_pp_kd",
      "n_charts": 12,
      "description": "GDP per capita based on purchasing power parity (PPP)."
    }
  ],
  "query": "gdp",
  "total_results": 1
}
❌ 422 - Validation Error

Content-Type: application/json

Schema: HTTPValidationError

Schemas

HTTPValidationError

Properties
Property Type Required Description
detail array[ValidationError]

SemanticSearchResponse

JSON schema for semantic search response.

Properties
Property Type Required Description
results array[SemanticSearchResult] ✓
query string ✓
total_results integer ✓

SemanticSearchResult

JSON schema for individual semantic search result.

Properties
Property Type Required Description
title string ✓
indicator_id integer ✓
snippet string ✓
score number ✓
metadata object ✓
catalog_path any
n_charts integer
description any
popularity number

ValidationError

Properties
Property Type Required Description
loc array[any] ✓
msg string ✓
type string ✓
input any
ctx object