esearch-api

Search API for Hive content. It powers search, tag/related-post discovery and the document counter behind hivesearcher.com and Ecency, querying an Elasticsearch index of posts and comments.

A small Flask + gunicorn app exposing:

Endpoint	Method	Purpose
/search	POST	Full-text search (scroll pagination)
/search-paged	POST	Full-text search (page-number pagination)
/similar	POST	"Read next" / related posts (More Like This)
/search-path	POST	Resolve author/permlink paths
/search-follower/<account>, /search-following/<account>	GET	Follow-graph lookups
/stats	GET	Index document count
/state	GET	API-key usage / daily limit

Full request/response reference: hivesearcher.com/api-docs.

Search ranking

/search and /search-paged accept a sort parameter:

• relevance (default) — BM25 text relevance weighted by post value, so genuinely useful posts outrank bare keyword matches that have no engagement.
• popularity — fresh and valuable: relevance multiplied by payout and a 30-day recency decay, while staying on-topic.
• newest — most recent first.

Spam (grayed / heavily-flagged) and NSFW content are filtered out by default; pass include_nsfw: 1 to opt in.

Requirements

• Python 3.8+
• Elasticsearch 8.x (the post index)
• PostgreSQL (API keys + request logs, and the eSync DB for path/follow lookups)

Configuration

All settings come from environment variables, conventionally placed in a gitignored env.sh. Copy the example and fill it in:

cp env.sh.example env.sh

Variable	Required	Description
ES_URI	yes	Elasticsearch URL
ES_INDEX	yes	Post index name
ES_USER / ES_PASS	no	Elasticsearch basic auth
ES_CA	no	CA cert path; set to verify TLS
DB_URI	yes	PostgreSQL — API keys & request logs
ESYNC_URI	yes	PostgreSQL — eSync DB (path / follower lookups)

Setup

python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp env.sh.example env.sh    # then edit

Running

set -a; source env.sh; set +a

# Development server (127.0.0.1:8089)
python run.py api

# Tests
python run.py test

# Production (gunicorn)
PYTHONPATH=src gunicorn esearch_api.app:app --workers 4 --bind 127.0.0.1:5001 --timeout 60

Deployment

The service runs under gunicorn, managed by systemd. A unit sources env.sh and launches the app, e.g.:

[Service]
WorkingDirectory=/opt/esearch-api/src
ExecStart=/bin/bash -c 'set -a; source /opt/esearch-api/env.sh; set +a; \
  exec /opt/esearch-api/venv/bin/gunicorn esearch_api.app:app \
  --workers 4 --bind 127.0.0.1:5001 --timeout 60'
Restart=always

Deploying a new version:

git pull
source venv/bin/activate && pip install -r requirements.txt   # only if deps changed
sudo systemctl restart esearch-api

Config lives in env.sh on the host (not in the repo), so it is preserved across deploys — a code update is just git pull + service restart.