API Documentation

List Countries with Stats

GET /api/v1/countries

Get all countries with project and entity statistics. This endpoint provides geographic data showing the global distribution of decentralized identity initiatives. You can optionally include detailed lists of projects, entities, and regulations for each country.

Request

Query Parameters

⚠️ Large Response Warning
If you set true on multiple, the respnse will be 1MB+ in size

Parameter Type Required Default Description
include_projects_hq boolean No false Include list of all projects headquartered in each country
include_entities_hq boolean No false Include list of all entities headquartered in each country
include_projects_target boolean No false Include list of all projects targeting each country
include_regulations boolean No false Include list of all regulations from each country

Example Requests

bash 
# Get all countries with basic statistics only
curl -X GET "https://www.weboftrust.org/api/v1/countries" \
  -H "X-API-Key: YOUR_API_KEY"

# Get countries with projects headquartered in each
curl -X GET "https://www.weboftrust.org/api/v1/countries?include_projects_hq=true" \
  -H "X-API-Key: YOUR_API_KEY"

# Get countries with entities headquartered in each
curl -X GET "https://www.weboftrust.org/api/v1/countries?include_entities_hq=true" \
  -H "X-API-Key: YOUR_API_KEY"

# Get countries with projects targeting them
curl -X GET "https://www.weboftrust.org/api/v1/countries?include_projects_target=true" \
  -H "X-API-Key: YOUR_API_KEY"

# Get countries with all related data
curl -X GET "https://www.weboftrust.org/api/v1/countries?include_projects_hq=true&include_entities_hq=true&include_projects_target=true&include_regulations=true" \
  -H "X-API-Key: YOUR_API_KEY"

Response

Success Response (200 OK)

Response Schema

typescript 
interface CountryListResponse {
  data: Country[];
}

interface Country {
  id: number;
  name: string;
  code: string;         // ISO 3166-1 alpha-2 code
  formal_name?: string; // Official country name
  stats: {
    entities: number;       // Number of entities headquartered here
    projects_hq: number;    // Projects with HQ in this country
    projects_target: number; // Projects targeting this country
    regulations: number;    // Regulations from this country
  };
  projects_hq?: Project[];      // Only included when include_projects_hq=true (all projects)
  entities_hq?: Entity[];       // Only included when include_entities_hq=true (all entities)
  projects_target?: Project[];  // Only included when include_projects_target=true (all projects)
  regulations?: Regulation[];   // Only included when include_regulations=true (all regulations)
}

interface Project {
  id: number;
  title: string;
  type: "DID Project" | "Consortium";
  status?: string;
  website?: string;
  source?: string;    // For projects_target: URL confirming project targets this country
}

interface Entity {
  id: number;
  name: string;
  type: string[];
  website?: string;
  lei?: string;
}

interface Regulation {
  id: number;
  title: string;
  official_name?: string;
  url?: string;
}

Example Response

json 
{
  "data": [
    {
      "id": 1,
      "name": "Afghanistan",
      "code": "AF",
      "formal_name": "Islamic State of Afghanistan",
      "stats": {
        "entities": 0,
        "projects_hq": 0,
        "projects_target": 0,
        "regulations": 0
      }
    },
    {
      "id": 17,
      "name": "Belgium",
      "code": "BE",
      "formal_name": "Kingdom of Belgium",
      "stats": {
        "entities": 58,
        "projects_hq": 12,
        "projects_target": 32,
        "regulations": 0
      }
    },
    {
      "id": 197,
      "name": "United States of America",
      "code": "US",
      "formal_name": "United States of America",
      "stats": {
        "entities": 487,
        "projects_hq": 89,
        "projects_target": 112,
        "regulations": 15
      }
    },
    {
      "id": 178,
      "name": "Singapore",
      "code": "SG",
      "formal_name": "Republic of Singapore",
      "stats": {
        "entities": 42,
        "projects_hq": 18,
        "projects_target": 25,
        "regulations": 3
      }
    }
  ]
}

Example Response (with included data)

json 
{
  "data": [
    {
      "id": 167,
      "name": "Singapore",
      "code": "SG",
      "formal_name": "Republic of Singapore",
      "stats": {
        "entities": 42,
        "projects_hq": 18,
        "projects_target": 25,
        "regulations": 3
      },
      "projects_hq": [
        {
          "id": 118,
          "title": "TradeTrust",
          "type": "DID Project",
          "status": "Launched",
          "website": "https://www.tradetrust.io/"
        }
      ],
      "entities_hq": [
        {
          "id": 36,
          "name": "Infocomm Media Development Authority",
          "type": ["Public"],
          "website": "https://www.imda.gov.sg/",
          "lei": null
        }
      ],
      "projects_target": [
        {
          "id": 325,
          "title": "EU Digital Identity Wallet",
          "type": "DID Project",
          "status": "Pilot",
          "website": "https://ec.europa.eu/digital-building-blocks/sites/display/EUDIGITALIDENTITYWALLET/EU+Digital+Identity+Wallet+Home",
          "source": "https://did-map-resources.s3.amazonaws.com/Southeast+Asia/Singapore/geographic_focus.pdf"
        }
      ],
      "regulations": [
        {
          "id": 23,
          "title": "Personal Data Protection Act",
          "official_name": "Personal Data Protection Act 2012",
          "url": "https://www.pdpc.gov.sg/Overview-of-PDPA/The-Legislation/Personal-Data-Protection-Act"
        }
      ]
    }
  ]
}

Error Responses

500 Internal Server Error

json 
{
  "error": {
    "code": "internal_error",
    "message": "Failed to fetch countries"
  }
}

Statistics Explained

entities

Number of organizations (both public and private) headquartered in this country. Includes:

  • Government agencies
  • Private companies
  • Standards organizations
  • Research institutions

projects_hq

Number of decentralized identity projects and consortia with headquarters in this country. This indicates where projects are primarily managed from.

projects_target

Number of projects that target or operate in this country. This may be higher than projects_hq as projects often target multiple countries.

regulations

Number of regulatory frameworks originating from this country that affect digital identity.

Country Codes

All country codes follow the ISO 3166-1 alpha-2 standard:

  • US - United States
  • GB - United Kingdom
  • DE - Germany
  • FR - France
  • CN - China
  • JP - Japan
  • SG - Singapore
  • CH - Switzerland

Use Cases

  • Geographic Analysis: Understand global distribution of DID initiatives
  • Market Research: Identify countries with high DID activity
  • Regulatory Mapping: Find countries with digital identity regulations
  • Investment Analysis: Discover emerging markets for digital identity
  • Partnership Opportunities: Identify countries with active ecosystems

Data Insights

Countries with high statistics typically indicate:

  • High entities count: Strong ecosystem with many participating organizations
  • High projects_hq: Innovation hub for digital identity
  • High projects_target: Market seen as important for digital identity adoption
  • High regulations: Advanced regulatory framework for digital identity

Performance Notes

  • This endpoint returns all countries in a single response
  • Base response is relatively small (~200 countries)
  • Setting any include_* parameter will significantly increase response size
  • When all include_* parameters are true, response can be very large (includes all projects and entities)
  • Results are cached for performance
  • No pagination needed for the country list itself