Developer Hub

Build with Tunisia's Knowledge

Public API, MCP server, structured datasets. No auth required. First successful call in under 5 minutes.

Quickstart API Reference MCP Guide

Choose Your Path

Consumer Answers

Journalists, researchers, curious minds

Browse answer pages
Read llms.txt for discovery
Use Markdown negotiation: Accept: text/markdown

< 5 min

API Integrator

Developers building apps & dashboards

Read API index
Explore Swagger UI
Run 3 curl examples below

< 15 min

MCP Integrator

AI/LLM developers connecting agents

MCP endpoint: /mcp
16 tools, Streamable HTTP
Works with Claude, GPT, custom agents

< 20 min

Quickstart — 3 Calls

No API key. No auth. No rate limit on GET (POST limited to 10 req/min).

1. Search knowledge

# Unified search across all content
curl -s https://welovetunisia.com/api/v1/search?q=carthage | python -m json.tool

2. Get verified facts

# All verified facts with sources
curl -s https://welovetunisia.com/api/v1/facts | python -m json.tool

3. Browse entities

# UNESCO World Heritage Sites
curl -s "https://welovetunisia.com/api/v1/entities?type=UNESCOSite" | python -m json.tool

Python SDK (no dependency needed)

import requests

BASE = "https://welovetunisia.com/api/v1"

# Search
results = requests.get(f"{BASE}/search", params={"q": "renewable energy"}).json()
print(f"Found {results['total']} results")

# Get all UNESCO sites
sites = requests.get(f"{BASE}/entities", params={"type": "UNESCOSite"}).json()
for s in sites:
    print(f"  {s['title']['en']} — {s['properties'].get('governorate', '')}")

JavaScript / Node.js

const BASE = "https://welovetunisia.com/api/v1";

// Search for facts about tourism
const res = await fetch(`${BASE}/search?q=tourism`);
const data = await res.json();
console.log(`Found ${data.total} results`);

API Reference

Base URL: https://welovetunisia.com/api/v1 — All endpoints are GET, read-only, no auth.

Endpoint	Description	Params
`GET /api/v1/`	API index & module listing	-
`GET /api/v1/search`	Unified search across all types	`q` (required), `lang`, `limit`
`GET /api/v1/facts`	Verified facts	`q`, `category`, `limit`
`GET /api/v1/facts/{id}`	Single fact	-
`GET /api/v1/entities`	Knowledge entities	`query`, `type`, `limit`
`GET /api/v1/entities/{id}`	Single entity	-
`GET /api/v1/answers`	Pre-built Q&A	`q`, `limit`
`GET /api/v1/answers/{id}`	Answer with resolved evidence	-
`GET /api/v1/datasets`	Dataset registry	-
Histoire (12 000 years)
`GET /api/v1/histoire/periods`	7 historical periods	-
`GET /api/v1/histoire/timeline`	Timeline events	`start`, `end`, `period`, `limit`
`GET /api/v1/histoire/places`	Historical places & UNESCO	`type`, `period`, `unesco`
`GET /api/v1/histoire/characters`	Historical figures	`period`
`GET /api/v1/histoire/objects`	Museum artifacts	`period`, `type`
`GET /api/v1/histoire/stories`	Historical stories	-
`GET /api/v1/histoire/references`	546 reference documents	`category`, `q`, `limit`
`GET /api/v1/histoire/search`	Search historical data	`q`
Diaspora & Modules
`GET /api/v1/annuaire/search`	Diaspora members	`q`, `country`, `sector`, `limit`
`GET /api/v1/chapters`	Regional chapters	`country`
`GET /api/v1/tokten/briefs`	Expertise needs	`sector`
`GET /api/v1/volontariat/missions`	Volunteer missions	`type`, `sector`, `gov`
`GET /api/v1/hub/offers`	Tourism offers	-
`GET /api/v1/hub/stats`	Tourism statistics	-

Rate Limits & Errors

GET requests: No rate limit
POST requests: 10 req/min per IP
429 Too Many Requests: Wait 60 seconds
404 Not Found: {"error": "not found", "id": "..."}

MCP Server Guide

welovetunisia.com exposes a Model Context Protocol server with 16 tools.

Connection

Endpoint: https://welovetunisia.com/mcp
Transport: Streamable HTTP (JSON-RPC)
Auth: None required (Phase 1)
Supports: tools/list, tools/call

Claude Desktop Config

{
  "mcpServers": {
    "tunisia-knowledge": {
      "url": "https://welovetunisia.com/mcp"
    }
  }
}

Available Tools (16) — Detailed

Tool	Purpose	Input	Latency
`search_tunisia_knowledge`	Hybrid search across all content	`query` (required), `language`, `limit`	<200ms
`get_verified_answer`	Pre-built answer with evidence	`question` (required), `audience`, `language`	<100ms
`get_entity`	Canonical entity with relations	`entity_id` (required)	<50ms
`get_facts`	Verified facts by category	`category` (optional)	<50ms
`compare_options`	Compare destinations/investments	`type`, `constraints`	<200ms
`build_trip_plan`	Generate tourism itinerary	`preferences` (required)	<300ms
`search_history`	Historical content search	`query` (required)	<200ms
`get_timeline`	12 000 years of events	`start`, `end`, `period`	<200ms
`get_historical_places`	Places & UNESCO sites	`type`, `unesco`	<100ms
`search_diaspora_members`	Diaspora directory search	`query`	<200ms
`get_diaspora_chapters`	Regional chapters list	`country` (optional)	<100ms
`get_volunteer_missions`	Active volunteer missions	`type`, `sector`	<100ms
`get_tokten_needs`	Institutional expertise needs	`sector` (optional)	<100ms
`get_datasets`	Available datasets registry	none	<50ms

All tools are read-only. No quotas in Phase 1. Errors return {"error": "description"} in content.

Service Status

Check /health for real-time service status (DB, Redis, LLM, TTS, payments).

Changelog

/changelog — JSON format
/changelog?format=text — Human-readable
/feed.xml — Atom feed for agents

License: CC-BY-4.0 — Attribution required: welovetunisia.com | Contact: contact@welovetunisia.com