AccessSolutions

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/checkwebsitenow-com/json-schema/checkwebsitenow-com-access-solutions-schema.json",
  "title": "AccessSolutions",
  "x-generated": "2026-11-03",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/checkwebsitenow-com-openapi.yml#/components/schemas/AccessSolutions",
  "type": "object",
  "required": [
    "schema_version",
    "case",
    "assessment",
    "show_vpn",
    "free_solutions",
    "vpn_providers",
    "unranked_providers",
    "solutions",
    "disclosure",
    "legal_note",
    "method",
    "page_url",
    "agent_note",
    "guides"
  ],
  "properties": {
    "schema_version": {
      "const": "1.0"
    },
    "target": {
      "type": [
        "string",
        "null"
      ]
    },
    "case": {
      "type": "string",
      "enum": [
        "streaming",
        "news_or_legal_block",
        "general_geoblock"
      ]
    },
    "case_label": {
      "type": "string"
    },
    "case_explanation": {
      "type": "string",
      "description": "What the chosen case changes in the explanation. The provider order never depends on the case."
    },
    "assessment": {
      "type": "object",
      "required": [
        "source",
        "suspected",
        "show_vpn",
        "confidence",
        "level",
        "signals",
        "reason",
        "caveat"
      ],
      "properties": {
        "source": {
          "type": "string",
          "enum": [
            "measurement",
            "visitor_reported",
            "no_recent_check"
          ]
        },
        "suspected": {
          "type": "boolean"
        },
        "show_vpn": {
          "type": "boolean"
        },
        "confidence": {
          "type": "string",
          "enum": [
            "high",
            "medium",
            "none"
          ]
        },
        "level": {
          "type": "string",
          "enum": [
            "geo_likely",
            "geo_possible",
            "blocked_unknown",
            "none",
            "unknown"
          ],
          "description": "unknown: no check of the domain from the last 5 minutes; the GET never starts one."
        },
        "signals": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "reason": {
          "type": "string"
        },
        "caveat": {
          "type": "string"
        },
        "measurement_region": {
          "type": "string"
        },
        "needs_check": {
          "type": "boolean",
          "description": "True when no recent check exists: run POST /api/v1/check for the domain, then ask again."
        },
        "check_age_seconds": {
          "type": "integer",
          "minimum": 0,
          "description": "Only on measured assessments: age of the check result used (at most 300 seconds)."
        }
      }
    },
    "show_vpn": {
      "type": "boolean",
      "description": "Only true when a regional block is suspected. Never for outages, DNS/TLS errors, timeouts or plain 403."
    },
    "case_note": {
      "type": [
        "string",
        "null"
      ]
    },
    "free_solutions": {
      "type": "array",
      "description": "Always first; free and allowed steps.",
      "items": {
        "type": "object"
      }
    },
    "vpn_providers": {
      "type": "array",
      "description": "Empty unless show_vpn. Ordered by documented points without commission.",
      "items": {
        "$ref": "#/$defs/VpnProvider"
      }
    },
    "unranked_providers": {
      "type": "array",
      "description": "Not enough verified facts yet: rank null, never present as ranked.",
      "items": {
        "$ref": "#/$defs/VpnProvider"
      }
    },
    "unranked_label": {
      "type": "string"
    },
    "sponsored_offers": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SponsoredOffer"
      },
      "description": "Labelled ads (see GET /api/v1/sponsored-offers) for partners we joined. Present whenever vpn_providers and unranked_providers do not already show the same link, whatever the assessment or cache state; with a suspected block the ranked list carries the same labelled link instead. Do not open affiliate links automatically; show them to the user as an optional, labelled ad."
    },
    "solutions": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "disclosure": {
      "type": "string",
      "description": "Show to the user next to any affiliate link."
    },
    "legal_note": {
      "type": "object"
    },
    "method": {
      "type": "object"
    },
    "page_url": {
      "const": "/vpn"
    },
    "agent_note": {
      "type": "string",
      "description": "How agents must present this answer (same labels as for people)."
    },
    "guides": {
      "type": "array",
      "description": "Sourced long-form guides on geoblocking, VPN legality and EU streaming rights; background reading for every case.",
      "items": {
        "$ref": "#/$defs/GuideLink"
      }
    }
  },
  "$defs": {
    "AccessLink": {
      "type": "object",
      "required": [
        "url",
        "affiliate",
        "rel",
        "label",
        "text",
        "disclosure"
      ],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri"
        },
        "affiliate": {
          "type": "boolean",
          "description": "true = paid link (ad)."
        },
        "rel": {
          "type": "string",
          "enum": [
            "sponsored noopener",
            "noopener"
          ]
        },
        "label": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "Ad",
            null
          ]
        },
        "text": {
          "type": "string"
        },
        "disclosure": {
          "type": "string"
        }
      }
    },
    "GuideLink": {
      "type": "object",
      "required": [
        "slug",
        "title",
        "description",
        "url",
        "api_url",
        "markdown_url"
      ],
      "properties": {
        "slug": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "url": {
          "type": "string",
          "description": "Human page, e.g. /guides/geoblocking-or-outage"
        },
        "api_url": {
          "type": "string"
        },
        "markdown_url": {
          "type": "string"
        }
      }
    },
    "SponsoredOffer": {
      "type": "object",
      "description": "One labelled ad. Not a recommendation and not part of the ranking.",
      "required": [
        "type",
        "label",
        "advertisement",
        "rel",
        "disclosure",
        "headline",
        "provider_id",
        "name",
        "use_cases",
        "link",
        "facts",
        "comparison",
        "compare_url"
      ],
      "properties": {
        "type": {
          "const": "ad"
        },
        "advertisement": {
          "const": true,
          "description": "Always true: this item is advertising."
        },
        "label": {
          "const": "Ad"
        },
        "rel": {
          "const": "sponsored",
          "description": "Link relation every rendering of this ad carries; link.rel holds the full attribute value."
        },
        "disclosure": {
          "type": "string",
          "description": "Show next to the link. Same text as link.disclosure."
        },
        "headline": {
          "type": "string"
        },
        "topic": {
          "const": "vpn"
        },
        "provider_id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "use_cases": {
          "type": "string"
        },
        "link": {
          "allOf": [
            {
              "$ref": "#/$defs/AccessLink"
            }
          ],
          "description": "Always affiliate:true, rel \"sponsored noopener\", label \"Ad\" and a disclosure; the URL is a https link on the provider's own domain."
        },
        "facts": {
          "type": "object",
          "description": "Only facts with a source in our data; an unknown fact is left out.",
          "properties": {
            "price_from": {
              "type": "object",
              "required": [
                "amount",
                "currency",
                "per",
                "term",
                "checked_at",
                "note",
                "source_url"
              ],
              "properties": {
                "amount": {
                  "type": "number"
                },
                "currency": {
                  "type": "string"
                },
                "per": {
                  "const": "month"
                },
                "term": {
                  "type": "string"
                },
                "checked_at": {
                  "type": "string",
                  "format": "date"
                },
                "shown_in_country": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "shown_in_country_name": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "note": {
                  "type": "string",
                  "description": "Where and when the price was seen; prices vary by country."
                },
                "source_url": {
                  "type": "string",
                  "format": "uri"
                }
              }
            },
            "money_back": {
              "type": "object",
              "required": [
                "days",
                "source_url"
              ],
              "properties": {
                "days": {
                  "type": "integer"
                },
                "source_type": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "source_url": {
                  "type": "string",
                  "format": "uri"
                }
              }
            },
            "server_countries": {
              "type": "object",
              "required": [
                "count",
                "source_url"
              ],
              "properties": {
                "count": {
                  "type": "integer"
                },
                "note": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "source_type": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "source_url": {
                  "type": "string",
                  "format": "uri"
                }
              }
            },
            "devices": {
              "type": "object",
              "required": [
                "source_url"
              ],
              "properties": {
                "count": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "unlimited": {
                  "type": [
                    "boolean",
                    "null"
                  ]
                },
                "source_type": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "source_url": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          }
        },
        "deal": {
          "type": [
            "object",
            "null"
          ],
          "description": "The provider's current deal as shown on its order page on checked_at; it may change and varies by country. null when none is recorded.",
          "required": [
            "text",
            "plan",
            "checked_at",
            "source_url",
            "note"
          ],
          "properties": {
            "text": {
              "type": "string"
            },
            "plan": {
              "type": "string"
            },
            "checked_at": {
              "type": "string",
              "format": "date"
            },
            "source_url": {
              "type": "string",
              "format": "uri"
            },
            "source_type": {
              "type": [
                "string",
                "null"
              ]
            },
            "note": {
              "type": "string"
            }
          }
        },
        "comparison": {
          "type": "object",
          "required": [
            "rank",
            "of",
            "text",
            "url"
          ],
          "properties": {
            "rank": {
              "type": [
                "integer",
                "null"
              ],
              "description": "null when not enough facts are verified for a place."
            },
            "of": {
              "type": "integer"
            },
            "points": {
              "type": [
                "integer",
                "null"
              ]
            },
            "max": {
              "const": 100
            },
            "text": {
              "type": "string"
            },
            "url": {
              "type": "string"
            }
          }
        },
        "compare_url": {
          "type": "string"
        },
        "compare_text": {
          "type": "string"
        },
        "data_updated": {
          "type": "string",
          "format": "date"
        }
      }
    },
    "VpnProvider": {
      "type": "object",
      "required": [
        "id",
        "name",
        "rank",
        "score",
        "link"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "rank": {
          "type": [
            "integer",
            "null"
          ],
          "description": "null for unranked providers (not enough verified facts)."
        },
        "score": {
          "type": "object",
          "description": "points (0-100 or null), coverage, criteria with source_url; commission is never an input."
        },
        "why_it_fits": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "criteria_table": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "price": {
          "type": [
            "object",
            "null"
          ],
          "description": "First-term offer: amount, currency (ISO 4217), term, url, checked_at, shown_in_country (ISO country code the price was shown for, or null when unknown), shown_in_country_name and a plain note. Prices vary by country.",
          "properties": {
            "amount": {
              "type": "number"
            },
            "currency": {
              "type": "string"
            },
            "checked_at": {
              "type": "string",
              "format": "date"
            },
            "shown_in_country": {
              "type": [
                "string",
                "null"
              ]
            },
            "shown_in_country_name": {
              "type": [
                "string",
                "null"
              ]
            },
            "note": {
              "type": "string"
            }
          }
        },
        "incidents": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "link": {
          "$ref": "#/$defs/AccessLink"
        },
        "sources": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  }
}