Skip to content
Bitelex Docs

Geo bans

A geo ban hides one record value from clients in an area. See DNS hosting.

interface GeoBan {
  uuid: string;
  record_id: string;   // uuid of the record value
  level: 'Region' | 'Subregion' | 'Country';
  code: number;
  created_at: number;
  updated_at: number;
}

Areas

Section titled “Areas”
level code Examples
Country ISO 3166-1 numeric 191 Croatia, 276 Germany, 840 United States
Subregion UN M49 39 Southern Europe, 30 Eastern Asia
Region UN M49 150 Europe, 142 Asia, 2 Africa

A code must exist at its level in the list of areas; any other is refused with 422. The CLI (dinio geo-ban areas) and the SDKs (parseGeoArea, parse_area) read that list and accept names and ISO letter codes (HR, HRV, Croatia, Europe) instead. For every code, see Geo areas.

List areas

Section titled “List areas”
GET /api/v1/geo

Every region, sub-region and country, with the code a ban takes. Use it to show names instead of numbers and to let people pick an area. It changes rarely: the response may be cached for a day.

Terminal window
curl -H "Authorization: Bearer $DINIO_API_KEY" https://api-dinio.bitelex.com/api/v1/geo
{
  "success": true,
  "data": {
    "regions": [{ "code": 150, "name": "Europe" }],
    "subregions": [{ "code": 39, "name": "Southern Europe", "region_code": 150 }],
    "countries": [
      {
        "code": 191,
        "alpha2": "HR",
        "alpha3": "HRV",
        "name": "Croatia",
        "region_code": 150,
        "subregion_code": 39
      }
    ]
  }
}

(Shortened: the real lists have every area.) A country’s region_code and subregion_code can be null.

Read bans

Section titled “Read bans”

There is no separate list route: bans are read with their record set, through Get a record set with include=geoBans.

Add a ban

Section titled “Add a ban”
POST /api/v1/geo-bans
Field Type
record_id uuid The record value: an A, AAAA, SRV or CNAME value.
level string Region, Subregion or Country.
code integer Area code for that level.
Terminal window
curl -X POST -H "Authorization: Bearer $DINIO_API_KEY" -H "Content-Type: application/json" \
  -d '{"record_id":"'$VALUE_ID'","level":"Country","code":191}' \
  https://api-dinio.bitelex.com/api/v1/geo-bans

Returns 201 with the ban. 422 for a code that is not in the list of areas at that level, or for a value of another type.

Change a ban

Section titled “Change a ban”
PATCH /api/v1/geo-bans/:uuid

Any of level, code.

Remove a ban

Section titled “Remove a ban”
DELETE /api/v1/geo-bans/:uuid

Optional query record_id: when given, the ban must belong to that value, or the call fails with 404 — a guard against removing another value’s ban by a mistyped uuid.

Terminal window
curl -X DELETE -H "Authorization: Bearer $DINIO_API_KEY" \
  "https://api-dinio.bitelex.com/api/v1/geo-bans/$BAN_ID?record_id=$VALUE_ID"