Hei!Local API documentation

The Hei!Local public API gives you programmatic access to the same search as the site: products from .ro shops and content (pages, companies, services) from .ro websites. Results are in Romanian.

1. API key

1. Sign in to your Hei!Local account and open AI connection.
2. Activate the Free plan (you accept the API terms).
3. Click Generate. The key (hl_…) is shown only once: store it. You can revoke or regenerate it at any time from the same place.

Send the key in the X-API-Key header (or Authorization: Bearer hl_…). Never put it in a URL or ship it in browser code.

2. Endpoints

Modes

Request body (JSON)

3. Examples

curl

curl -X POST "https://heilocal.ro/api/v1/products/search?mode=processed" \
  -H "X-API-Key: hl_your_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "geacă de iarnă bărbați", "limit": 5, "price_max": 400}'

Python

import requests

r = requests.post(
    "https://heilocal.ro/api/v1/content/search",
    params={"mode": "raw"},
    headers={"X-API-Key": "hl_your_key"},
    json={"query": "instalator sanitar Cluj", "limit": 5},
    timeout=60,
)
r.raise_for_status()
for item in r.json()["results"]:
    print(item["title"], item["url"])

Response (products)

{
  "success": true,
  "mode": "processed",
  "query": "geacă de iarnă bărbați",
  "offset": 0,
  "limit": 5,
  "count": 5,
  "results": [
    {
      "title": "Geacă bărbați de iarnă îmblănită",
      "url": "https://magazin.ro/produs/...",
      "domain": "magazin.ro",
      "ai_category": "Imbracaminte",
      "image": "https://heilocal.ro/api/img/…?w=800",
      "score": 0.83
    }
  ],
  "credits": {"charged": 5, "today": {"used": 12, "limit": 100}, "month": {"used": 40, "limit": 1000}}
}

For content, each result has title, url, domain, category, snippet (a short summary, max. 300 characters) and score. In processed mode the response may also carry low_confidence: true (near-misses) or relevance_gap (the top results do not match a requested colour or attribute).

4. Prices

price_min and price_max are filters only, in both modes. In processed mode the price understood from the text ("sub 500 de lei") is applied too; when both exist, the narrower range wins.

• Only about 73% of products have an extracted price. Products without one drop out of any price filter.
• The filter uses the last price Hei!Local saw, not today's: for roughly 1 in 6 products the price has changed since on the shop's site.

5. Limits and credits (Free plan)

Only successful searches are charged. Days and months are counted in UTC. Every response carries X-RateLimit-Limit (credits per day), X-RateLimit-Remaining and X-RateLimit-Reset (the daily reset, Unix seconds). Your daily usage is in AI connection.

Searches made by your AI assistant through the MCP server need the same active plan and use the same credits (5 per search).

6. Errors

Error body: {"success": false, "error": "…"}.

7. Rules

Use of the API is subject to the API terms. Systematic extraction of the catalogue and redistribution of the data are forbidden. For higher volumes, write to hei@heilocal.ro.