Casinos API

The Casinos API provides comprehensive access to SAPIENTRIS's casino database, including both online and land-based casinos with detailed information, ratings, and intelligence.

Base Endpoint

https://api.sapientris.com/v1/casinos

Endpoints

List All Casinos

GET /v1/casinos

Retrieve a paginated list of all casinos in the database.

Query Parameters

| Parameter | Type | Description | Default | |-----------|------|-------------|---------| | page | integer | Page number | 1 | | per_page | integer | Items per page (max 100) | 20 | | market | string | Filter by market (e.g., 'de', 'uk', 'global') | all | | license_status | string | Filter by license status ('licensed', 'grey', 'crypto') | all | | is_active | boolean | Filter by active status | true | | category | string | Filter by category ('online', 'land_based') | all | | min_rating | float | Minimum safety rating (0-10) | 0 | | search | string | Search in casino names and descriptions | - |

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.sapientris.com/v1/casinos?market=de&license_status=licensed&per_page=50"

Example Response

{
  "data": [
    {
      "id": 1,
      "name": "Casino Winner",
      "slug": "casino-winner",
      "description": "Premium German licensed casino",
      "website_url": "https://casino-winner.de",
      "logo_url": "https://cdn.sapientris.com/logos/casino-winner.png",
      "license_status": "licensed",
      "license_info": {
        "authority": "German Gaming Authority (GGL)",
        "license_number": "DE-12345",
        "issued_date": "2021-07-01",
        "expires_date": "2024-06-30"
      },
      "ratings": {
        "overall": 8.5,
        "safety": 9.2,
        "games": 8.1,
        "bonuses": 7.8,
        "support": 8.9
      },
      "markets": ["de"],
      "currencies": ["EUR"],
      "languages": ["de", "en"],
      "features": [
        "live_chat",
        "mobile_optimized",
        "crypto_payments",
        "responsible_gambling"
      ],
      "game_providers": [
        "NetEnt",
        "Microgaming",
        "Play'n GO"
      ],
      "payment_methods": [
        "visa",
        "mastercard",
        "paypal",
        "skrill",
        "bitcoin"
      ],
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-08-05T14:22:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1250,
    "total_pages": 63,
    "has_next": true,
    "has_prev": false
  }
}

Get Casino Details

GET /v1/casinos/{casino_id}

Retrieve detailed information about a specific casino.

Path Parameters

| Parameter | Type | Description | |-----------|------|-------------| | casino_id | integer/string | Casino ID or slug |

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.sapientris.com/v1/casinos/casino-winner"

Casino Performance Metrics

GET /v1/casinos/{casino_id}/performance

Get performance analytics for a specific casino.

Example Response

{
  "casino_id": 1,
  "metrics": {
    "traffic_score": 85,
    "conversion_rate": 3.2,
    "player_retention": {
      "day_1": 45,
      "day_7": 25,
      "day_30": 12
    },
    "average_deposit": 125.50,
    "player_value": {
      "ltv": 450.75,
      "avg_session_duration": 35
    },
    "affiliate_performance": {
      "click_through_rate": 2.8,
      "conversion_rate": 3.2,
      "revenue_share": 35
    }
  },
  "updated_at": "2024-08-05T12:00:00Z"
}

Casino Comparison

GET /v1/casinos/compare

Compare multiple casinos side by side.

Query Parameters

| Parameter | Type | Description | |-----------|------|-------------| | casino_ids | string | Comma-separated casino IDs | Required | | metrics | string | Comma-separated metrics to compare | all |

Trending Casinos

GET /v1/casinos/trending

Get currently trending casinos based on various factors.

German Market Specific

Licensed German Casinos

GET /v1/de/casinos

Get only German-licensed casinos compliant with Glücksspielstaatsvertrag.

Additional Fields for German Market

{
  "ggl_compliance": {
    "license_number": "DE-12345",
    "issued_by": "Gemeinsame Glücksspielbehörde der Länder",
    "issued_date": "2021-07-01",
    "compliance_score": 9.5,
    "restrictions": [
      "€1000_monthly_deposit_limit",
      "5_second_spin_limit",
      "no_autoplay"
    ]
  },
  "responsible_gambling": {
    "self_exclusion": true,
    "deposit_limits": true,
    "time_limits": true,
    "reality_checks": true
  }
}

Land-Based Casinos (Spielhallen)

List Spielhallen

GET /v1/spielhallen

Get land-based casino locations (Spielhallen) in Germany.

Additional Query Parameters

| Parameter | Type | Description | |-----------|------|-------------| | city | string | Filter by city | | postal_code | string | Filter by postal code | | operator | string | Filter by operator (e.g., 'merkur', 'vulkan') | | lat | float | Latitude for location search | | lng | float | Longitude for location search | | radius | integer | Search radius in kilometers |

Example Response

{
  "data": [
    {
      "id": 1001,
      "name": "MERKUR Spielothek Berlin Mitte",
      "operator": "MERKUR",
      "address": {
        "street": "Friedrichstraße 123",
        "city": "Berlin",
        "postal_code": "10117",
        "country": "DE"
      },
      "location": {
        "latitude": 52.5200,
        "longitude": 13.4050
      },
      "contact": {
        "phone": "+49 30 12345678",
        "email": "berlin-mitte@merkur.de"
      },
      "operating_hours": {
        "monday": "10:00-02:00",
        "tuesday": "10:00-02:00",
        "sunday": "12:00-24:00"
      },
      "features": [
        "wheelchair_accessible",
        "parking_available",
        "food_service"
      ],
      "machine_count": 45,
      "quality_score": 85
    }
  ]
}

Rate Limits

Free Tier: 1,000 requests per hour
Premium Tier: 10,000 requests per hour
Enterprise: Custom limits

Error Responses

404 Not Found

{
  "error": "Casino not found",
  "message": "The requested casino does not exist"
}

422 Validation Error

{
  "error": "Validation failed",
  "message": "Invalid query parameters",
  "details": {
    "per_page": ["Must be between 1 and 100"]
  }
}