Overview
The Geo & ISP restriction allows you to include or exclude certain Countries and/or ISPs from the Lumen Delivery Products activation. With these set of APIs, it is possible to Whitelist or Blacklist Countries and/or ISPs where you want Mesh Delivery to be activated or deactivated depending on your business requirements.
Changes made to a Geo & ISP restriction take up to 10 minutes to be effective.
What is a Geo/ISP Restriction List
A Geo/ISP Restriction List can be created by defining the following fields:
| Fields | Type | Description |
| name | string | The name of the Geo/ISP restriction list. Example: "Whitelist France". |
| type | string | The type of the list. Possible values are "blacklist" and "whitelist". |
| countries | string |
The list of country names where you want to activate/deactivate Mesh Delivery. The country names are case insensitive and must match To retrieve the format of the Countries are updated twice a week. |
| isps | string |
The list of Internet Service Provider where you want to activate/deactivate Mesh Delivery. ISP names are case insensitive and must match To retrieve the format of the ISPs are updated twice a week. |
| <YOUR_CUSTOMER_ID> | String |
<YOUR_CUSTOMER_ID> is a string parameter which is the unique Customer ID that you are assigned for the Product(s) that you use. It can be found in the Company Tab of the Profile Section. |
| <YOUR_LIST_ID> | String | <YOUR_LIST_ID> is the geoblockingListId that is used to identify a Geo/ISP Restriction List. You can use this to point to particular list in an API end point. |
Empty Lists
While entering data in a field within a list, it is possible to have some fields where no data has been entered, i.e the field is empty. In that case, an empty list corresponds to missing field.
If a field within a list has no data in it, then it is considered to be a missing field.
Example:
This entry,
{
"name":"test empty ISP whitelist",
"type":"whitelist",
"countries": ["United Kingdom"],
"isp":[]
}
{
"name":"test empty ISP whitelist",
"type":"whitelist",
"countries":["United Kingdom"]
}
Relationships between Countries and ISPs
When calling an API, it is important to keep in mind the relationships between the Countries and ISPs. The relationship differs depending on whether the list has been Blacklisted or Whitelisted. The fields are related in the following way:
Blacklist
- When defining a blacklist, we’ll exclude from the Mesh Delivery users who belong to the list of Countries OR the list of ISPs
- When a blacklist rule is defined, only the clients whose IP matches the rule are deactivated, all others are activated.
Example
{
"name":"DNA_Config_1.1",
"type":"blacklist",
"countries":["France", "Italy"],
"isps":["Orange France Mobile", "Wind Tre"]
}This list will result in all the viewers located in France & Italy (regardless of their ISP) as well as all viewers connected to the Orange France Mobile and Wind Tre (regardless of their country) being deactivated.
Whitelist
- When defining a blacklist, we’ll exclude from Mesh Delivery users who belong to the list of Countries AND the list of ISPs
- When a whitelist rule is defined, only the clients whose IP matches the rule are activated, all the rest are deactivated.
Example
{
...
"type":"whitelist",
"countries":["United Kingdom", "Spain"],
"isps":["CenturyLink", "Wind Tre"]
}This list will result in all the viewers located in United Kingdom & Spain who are connected to either Orange France Mobile or Wind Tre being deactivated.
Step by step guide to setup a Geo/ISP Restriction List
In order to fully setup and implement a Geo/ISP Restriction List using our APIs, follow the following steps:
1. Create a Geo/ISP Restriction List
Create a Geo/ISP Restriction List using the following end-point.
With this end point, you define which countries and/or ISPs would be blacklisted or whitelisted.
2. Attach a Geo/ISP Restriction List to a Mesh Delivery Property
This allows you to attach a Geo/ISP Restriction Rule created by defining a Whitelist/Blacklist to a Property in Mesh Delivery.
For a Restriction list to be active, it needs to be attached to a Property .
This means that you can use different restriction lists for different properties.
The link will be done via the field geoblockingListId :
"geoblockingListId" : <YOUR_LIST_ID>
Endpoint
POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/properties
Request Body Example
{
"name": "testGeoIspList",
"activationRatio": 1,
"superSeederRatio": 1,
"detectRangeRequests": true,
"networkActivation": {
"wifiEthernetUpload": true,
"wifiEthernetDownload": true,
"cellularOtherDownload": true,
"cellularOtherUpload": true
},
"ssai": {
"enabled": false,
"provider": "",
"options": ""
},
"geoblockingListId": <YOUR_LIST_ID>
}
Response Example
{
"name": "property1",
"activationRatio": 1,
"superSeederRatio": 1,
"detectRangeRequest": false,
"geoblockingListId": "<YOUR_LIST_ID>",
"networkActivation": {
"wifiEthernetUpload": true,
"wifiEthernetDownload": true,
"cellularOtherUpload": true,
"cellularOtherDownload": true
},
"ssai": {
"enabled": false,
"provider": "",
"options": ""
},
"enterprise": {
"customStunUrls": [],
"customSignalingUrl": "",
"localNetworkOnly": false,
"matching": false,
"matchingMap": false,
"matchingMask": false,
"unknownSubnetAllow": false,
"mask": 0
}
}
3. Get the Property the List is attached to
To double check that the setup is successful, you can get the Property that has the Geo & ISP List attached by using the following endpoint:
GET api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/dna/properties/{YOUR_PROPERTY_NAME}
Available APIs
List of API endpoints
Given below is a list of all the API endpoints that can be used in order to set up Geo/ISP Restriction Lists:
POST // Create a Geo/ISP Restriction List: api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/geo-isp-restrictions/lists
GET // Get all Geo/ISP Restriction Lists: api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/geo-isp-restrictions/lists
GET // Get one Geo/ISP Restriction List: api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/geo-isp-restrictions/lists/{{YOUR_LIST_ID}}
PUT // Update a Geo/ISP Restriction List: api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{{YOUR_LIST_ID}}
DEL // Delete a Geo/ISP Restriction List: api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{{YOUR_LIST_ID}}
Create a Geo/ISP Restriction List
Allows to define a whitelist or blacklist of countries/ISPs to activate/deactivate Mesh Delivery.
Endpoint
POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists
For Blacklist
Request Body Example for Blacklist
{
"name":"DNA_Config_1.1",
"type":"blacklist",
"countries":["France", "Italy"],
"isps":["Orange France Mobile", "Wind Tre"]
}
{
"data": {
"countries": [
"France",
"Italy"
],
"customerId": <YOUR_CUSTOMER_ID>,
"id": <YOUR_LIST_ID>,
"isps": [
"Orange"
],
"name": "DNA_Config_black_test1",
"type": "blacklist"
}
}
For Whitelist
{
...
"type":"whitelist",
"countries":["United Kingdom", "Spain"],
"isps":["CenturyLink", "Wind Tre"]
}
{
"data": {
"countries": [
"United Kingdom",
"Spain"
],
"customerId": "",
"id": "",
"isps": [
"CenturyLink",
"Wind Tre"
],
"name": "DNA_Config_white_test2",
"type": "whitelist"
}
}
Get a particular Geo/ISP Restriction List
This can be used to get a particular Geo/ISP Restriction List
End Point
GET api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{{YOUR_LIST_ID}}
Response Example
{
"data": {
"countries": [
"france"
],
"customerId": <YOUR_CUSTOMER_ID>,
"id": <YOUR_LIST_ID>,
"name": "DNA_Config_1.1",
"type": "blacklist"
}
}
Get all Geo/ISP Restriction Lists
This can be used to get all the active Geo/ISP Restriction Lists
End Point
GET api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists
Response Example
{
"data": [
{
"countries": [
"france"
],
"customerId": <YOUR_CUSTOMER_ID>,
"id": <YOUR_LIST_ID>,
"name": "DNA_Config_1.1",
"type": "blacklist"
},
{
"countries": [
"france"
],
"customerId": <YOUR_CUSTOMER_ID>,
"id": <YOUR_LIST_ID>,
"name": "DNA_Config_1.2",
"type": "blacklist"
}
]
}
Update a Geo/ISP Restriction List
This can be used to update a particular Geo/ISP Restriction List
End Point
PUT api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{YOUR_LIST_ID}
Request Body Example
{
"name":"Whitelist (FR) (Orange France Mobile, SFR) - updated",
"type": "whitelist",
"countries" : ["France"],
"isps":["Orange France Mobile", "SFR"]
}
Response Example
Delete a Geo/ISP Restriction List
This can be used to delete a particular Geo/ISP Restriction List.
End Point
DELETE api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{YOUR_LIST_ID}
Response Example
Errors
HTTP 400
{
"message": "invalid listId"
}
HTTP 500
{
"error": "empty activation rule is not allowed"
}
Authentication
API Key
To use our Data APIs you need to authenticate via API Key. You can get your API Keys from the Dashboard in the Profile Section:
Customer ID
You will also need your Customer ID which can be found in the Company tab of the Profile section:
Authenticate via API Key
To use our data APIs you need to authenticate via API Key set in the Authorization HTTP header.
Once you have the key, simply add this header to your HTTP requests:
Authorization: API-Key {YOUR_API_KEY}