Hostname Country Identification

Throttle (Free Tier): 50/Hour
Throttle (Paid Tier): Pricing

Examples:

Objects and Endpoints:

Object: Hostname

This Object DOES NOT do a DNS lookup! The Hostname is validated and the CCTLD is checked.
IP Addresses should NOT be validated against Hostnames! Use the IP Endpoints!
hostname
String
This is the IDNA representation of the hostname.

Example

"hostname": "royal.uk"
gdpr
Boolean
Is this Hostname Subject to the GDPR?

Example

"gdpr": true
location
String
ISO 3166-1 alpha-2 Country Code
The Location of "ZZ" references an Unknown or Invalid Territory

Most TLDs such as .com, .net, or .org do not represent any one nation so a location of ZZ is returned.

Example

"location": "UK"
location-full
String
Full Location Name

Example

"location-full": "United Kingdom"
extended
Object: Hostname
This is the optionally fully detailed Validated Hostname

extended=true must be past on Request for this Object to exist.


Object: Request

hostname
String
Hostname to Geographically lookup.

Example

"hostname": "royal.uk"
hostnames
[]String
Used for Bulk lookups only! This is for paid endpoints only!

Example

"hostnames": [
	"royal.uk",
	"gdpr-identity.com",
	"localhost"
]
date
String
YYYYMMDD - This is for History endpoints only!

Example

"date": "20180525"
validator
Number
Optional
Method of Validation to use.
STRICT Validation will not allow Incorrect Spec Validation to occur! It's recommended to use LOOSE!
The Default/Invalid Validator is LOOSE

Constants

Key Value
STRICT 1
LOOSE 2
EMAIL_STRICT 3
EMAIL_LOOSE 4


Example

"validator": 0
extended
Object: Hostname
Optional
This is the optionally fully detailed Validated Hostname

extended=true must be past on Request for this Object to exist.

options
Object: Extended Hostname Options
Optional
Extended Options, extended=true must be set to use!
Default Options will be used when nil

pd
Boolean
Optional
Percent Decode before validating? Only avaliable for GET endpoints!

Example

"pd": false
jsonp
String
Optional
Return a JSONP Object? Only avaliable for GET endpoints!

Example

"json": "myfunc"

Object: Result

Bulk Results are only avaliable for paid plans. To upgrade contact sales@gdpr-identity.com
hostname
Object: Hostname
Geolocation Result

hostnames
key[string]Hostname
Key contains the original validated Hostname, Value points to the Result.

Used for Bulk lookups only! This is for paid endpoints only!

throttled-until
String
Throttle Expiration Timestamp RFC 3339

Only exists when throttled!

Example

"throttled-until": "2006-01-02T15:04:05Z07:00"
throttle-acquired
Number
The number of actions you acquired from the throttle.
This is always 1 unless bulk endpoints are used.
Bulk will either acquire the amount of bulk actions you requested or the remaining amount of actions available in the throttle.

Example

"throttle-acquired": 1
throttle-available
Number
The number of actions remaining in the throttle.

Example

"throttle-available": 99
suspended
Boolean
This only exists for paid plans. The most likely reason for this is a billing issue. Please contact sales@gdpr-identity.com to resolve this.

Example

"suspended": false
error
Number
Returns non 0 on Error.

API_ERROR_INVALID will be returned when using Bulk if 1 or more IPs, Emails, Hostnames or Geolocations are Invalid. Valid Results will still be returned AS WELL!

Constants

Key Value
UNKNOWN 1
THROTTLED 2
INVALID 3
INVALID_TIMESTAMP 4
INVALID_BODY 5
INVALID_BULK_MAX 6


Example

"error": 1
errors
[]String
Debug Errors - Do not rely on these values, use Error to determine the reason.

Example

"errors": [
	"internal server error"
]

GET /api;v=1/hostname

To authenticate use /api;v=1;key=APIKEY/hostname?hostname=

Request

Request Example

curl 'https://gdpr-identity.com/api/hostname?hostname=royal.uk'

Response

Response Example

{
  "hostname": {
    "hostname": "royal.uk",
    "gdpr": true,
    "location": "UK",
    "location-full": "United Kingdom"
  },
  "throttle-acquired": 1,
  "throttle-available": 981
}

GET /api;v=1/hostname/after?

To authenticate use /api;v=1;key=APIKEY/hostname/after?

Request

Request Example

curl 'https://gdpr-identity.com/api/hostname/after?gdpr-identity.com'

Response

Response Example

{
  "hostname": {
    "hostname": "gdpr-identity.com",
    "location": "ZZ",
    "location-full": "Unknown or Invalid Territory"
  },
  "throttle-acquired": 1,
  "throttle-available": 980
}

POST /api;v=1/hostname

To authenticate use /api;v=1;key=APIKEY/hostname/

Request

Request Example

curl -H "Content-Type: application/json" --request POST --data '{"hostname":"juandefu.ca"}' 'https://gdpr-identity.com/api/hostname'

Response

Response Example

{
  "hostname": {
    "hostname": "juandefu.ca",
    "location": "CA",
    "location-full": "Canada"
  },
  "throttle-acquired": 1,
  "throttle-available": 979
}

POST /api;v=1;key=APIKEY/bulk/hostname

This is a paid only endpoint!

To authenticate use /api;v=1;key=APIKEY/bulk/hostname/

Request

Request Example

curl -H "Content-Type: application/json" --request POST --data '{"hostnames":["royal.uk","gdpr-identity.com","juandefu.ca"]}' 'https://gdpr-identity.com/api;key=APIKEY/bulk/hostname'

Response

Response Example

{
  "hostnames": {
    "royal.uk": {
      "hostname": "royal.uk",
      "gdpr": true,
      "location": "UK",
      "location-full": "United Kingdom"
    },
    "gdpr-identity.com": {
      "hostname": "gdpr-identity.com",
      "location": "ZZ",
      "location-full": "Unknown or Invalid Territory"
    },
    "juandefu.ca": {
      "hostname": "juandefu.ca",
      "location": "CA",
      "location-full": "Canada"
    }
  },
  "throttle-acquired": 3,
  "throttle-available": 994
}