IP Historical Geolocation

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

Examples:

Objects and Endpoints:

Object: IP

ip
String
Validated IP Address

If a raw IP Address of 127.00.0.1 or ::0 is looked up this value would be 127.0.0.1 or ::

Example

"ip": "8.8.8.8"
gdpr
Boolean
Is this IP Address Subject to the GDPR?

Example

"gdpr": false
inactive
Boolean
Is this IP Address currently unallocated? If so, the previously last known data is referenced.

If you have traffic that references this Date it should be assumed to either be the previously allocated data or is fraudulent data.

If you believe this may be incorrect please contact us at data-corrections@gdpr-identity.com

Example

"inactive": false
reserved
Boolean
Does this IP Address belong to a Reserved Network?

Example

"reserved": false
date
String
YYYYMMDD - Current Date or Historical Date

Example

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

Example

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

Example

"location-full": "United States of America"
extended
Object: IP
This is the optionally fully detailed Validated IP Address

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


Object: Request

ip
String
IP Address to Geographically lookup.

Example

"ip": "8.8.8.8"
ips
[]String
Used for Bulk lookups only! This is for paid endpoints only!

Example

"ips": [
	"127.0.0.1",
	"::",
	"8.8.8.8"
]
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 Validator is LOOSE

Constants

Key Value
STRICT 1
STRICT_ANY 2
STRICT_IPV4 3
STRICT_IPV4HISTORIC 4
STRICT_IPV6 5
LOOSE 6
LOOSE_ANY 7
LOOSE_IPV4 8
LOOSE_IPV4HISTORIC 9
LOOSE_IPV6 10


Example

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

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

options
Object: Extended IP 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
ip
Object: IP
Geolocation Result

ips
key[string]IP
Key contains the original validated IP, 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/current

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

Request

Request Example

curl 'https://gdpr-identity.com/api/current?ip=8.8.8.8'

Response

Response Example

{
  "ip": {
    "ip": "8.8.8.8",
    "date": "20180525",
    "location": "US",
    "location-full": "United States of America"
  },
  "throttle-acquired": 1,
  "throttle-available": 997
}

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

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

Request

Request Example

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

Response

Response Example

{
  "ip": {
    "ip": "fd00::",
    "reserved": true,
    "date": "20180525",
    "location": "ZZ",
    "location-full": "Unknown or Invalid Territory"
  },
  "throttle-acquired": 1,
  "throttle-available": 996
}

POST /api;v=1/current

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

Request

Request Example

curl -H "Content-Type: application/json" --request POST --data '{"ip":"193.0.6.139"}' 'https://gdpr-identity.com/api/current'

Response

Response Example

{
  "ip": {
    "ip": "193.0.6.139",
    "gdpr": true,
    "date": "20180525",
    "location": "NL",
    "location-full": "Netherlands"
  },
  "throttle-acquired": 1,
  "throttle-available": 995
}

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

This is a paid only endpoint!

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

Request

Request Example

curl -H "Content-Type: application/json" --request POST --data '{"ips":["8.8.8.8","fd00::","193.0.6.139"]}' 'https://gdpr-identity.com/api;key=APIKEY/bulk/current'

Response

Response Example

{
  "ips": {
    "8.8.8.8": {
      "ip": "8.8.8.8",
      "date": "20180525",
      "location": "US",
      "location-full": "United States of America"
    },
    "fd00::": {
      "ip": "fd00::",
      "reserved": true,
      "date": "20180525",
      "location": "ZZ",
      "location-full": "Unknown or Invalid Territory"
    },
    "193.0.6.139": {
      "ip": "193.0.6.139",
      "gdpr": true,
      "date": "20180525",
      "location": "NL",
      "location-full": "Netherlands"
    }
  },
  "throttle-acquired": 3,
  "throttle-available": 994
}

GET /api;v=1/history?date=YYYYMMDD&ip=

To authenticate use /api;v=1;key=APIKEY/history?date=YYYYMMDD

Request

Request Example

curl 'https://gdpr-identity.com/api/history?ip=193.0.6.139&date=20100203'

Response

Response Example

{
  "ip": {
    "ip": "193.0.6.139",
    "gdpr": true,
    "date": "20100203",
    "location": "EU",
    "location-full": "European Union"
  },
  "throttle-acquired": 1,
  "throttle-available": 993
}

GET /api;v=1/history/after;date=YYYYMMDD?

To authenticate use /api;v=1;key=APIKEY/history/after;date=YYYYMMDD?

Request

Request Example

curl 'https://gdpr-identity.com/api/history/after;date=20010101;jsonp?192.5.11.0'

Response

Response Example

GDPR({
  "ip": {
    "ip": "192.5.11.0",
    "date": "20010101",
    "location": "US",
    "location-full": "United States of America"
  },
  "throttle-acquired": 1,
  "throttle-available": 992
});

POST /api;v=1/history

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

Request

Request Example

curl -H "Content-Type: application/json" --request POST --data '{"date":"19960823","ip":"207.181.0.255"}' 'https://gdpr-identity.com/api/history'

Response

Response Example

{
	"ip": {
		"ip": "207.181.0.255",
		"gdpr": true,
		"date": "19960823",
		"location": "GB",
		"location-full": "United Kingdom of Great Britain and Northern Ireland"
	},
	"throttle-acquired": 1,
	"throttle-available": 991
}

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

This is a paid only endpoint!

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

Request

Request Example

curl -H "Content-Type: application/json" --request POST --data '{"date":"19960823","ips":["8.8.8.8","192.5.11.0","207.181.0.255"]}' 'https://gdpr-identity.com/api;key=APIKEY/bulk/history'

Response

Response Example

{
  "ips": {
    "8.8.8.8": {
      "ip": "8.8.8.8",
      "date": "20100113",
      "location": "US",
      "location-full": "United States of America"
    },
    "192.5.11.0": {
      "ip": "192.5.11.0",
      "date": "20100113",
      "location": "US",
      "location-full": "United States of America"
    },
    "207.181.0.255": {
      "ip": "207.181.0.255",
      "date": "20100113",
      "location": "US",
      "location-full": "United States of America"
    }
  },
  "throttle-acquired": 3,
  "throttle-available": 988
}