Latitude and Longitude Geolocation

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

Countries include their Maritime Boundaries and Oceans/Seas have a resolution of 1KM~

Examples:

Objects and Endpoints:

Object: Geolocation

latitude
Number
Latitude of Geolocation

Example

"latitude": 51.500785
longitude
Number
Longitude of Geolocation

Example

"longitude": -0.124596
gdpr
Boolean
Is this Geolocation Subject to the GDPR?

Example

"gdpr": true
ocean
Boolean
Is this Location within an Ocean or a Sea?

Ocean has a resolution of 1 KM~.
Maritime boundaries are included a countries location. Some countries may have Oceans or Sea within their area, or a location may be on an Ocean or Sea.

Example

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

Example

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

Example

"location-full": "United Kingdom"

Object: Request

latitude
Number
Latitude to Geographically lookup.
This is for NON Bulk lookups only!

Example

"latitude": 38.924154
longitude
Number
Longitude to Geographically lookup.
This is for NON Bulk lookups only!

Example

"longitude": -77.066448
geos
[]Object: Geo
Used for Bulk lookups only! This is for paid endpoints only!

Example

"geos": [
	{
		"latitude": 49.2844,
		"longitude": -123.108885
	},
	{
		"latitude": -33.906477,
		"longitude": 18.422157
	}
]
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
geo
Object: Geolocation
Geolocation Result

geos
key[string]Geolocation
Key contains the original validated Geolocation, 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/geo

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

Request

Request Example

curl 'https://gdpr-identity.com/api/geo?latitude=51.500785&longitude=-0.124596'

Response

Response Example

{
  "geo": {
    "latitude": 51.500785,
    "longitude": -0.124596,
    "location": "GB",
    "location-full": "United Kingdom of Great Britain and Northern Ireland",
    "gdpr": true
  },
  "throttle-acquired": 1,
  "throttle-available": 45
}

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

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

Request

Request Example

curl 'https://gdpr-identity.com/api/geo/after?38.924154,-77.066448'

Response

Response Example

{
  "geo": {
    "latitude": 38.924154,
    "longitude": -77.066448,
    "location": "US",
    "location-full": "United States of America"
  },
  "throttle-acquired": 1,
  "throttle-available": 49
}

POST /api;v=1/geo

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

Request

Request Example

curl -H "Content-Type: application/json" --request POST --data '{"latitude":19.72274,"longitude":-155.067439}' 'https://gdpr-identity.com/api/geo'

Response

Response Example

{
  "geo": {
    "latitude": 19.72274,
    "longitude": -155.067439,
    "location": "US",
    "location-full": "United States of America"
  },
  "throttle-acquired": 1,
  "throttle-available": 961
}

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

This is a paid only endpoint!

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

Request

Request Example

curl -H "Content-Type: application/json" --request POST --data '{"geos":[{"latitude":48.58204,"longitude":7.751387},{},{"latitude":49.2844,"longitude":-123.108885}]}' 'https://gdpr-identity.com/api;key=APIKEY/bulk/geo'

Response

Response Example

{
  "geos": {
    "0.000000,0.000000": {
      "location": "ZZ",
      "location-full": "Unknown or Invalid Territory",
      "ocean": true
    },
    "48.582040,7.751387": {
      "latitude": 48.58204,
      "longitude": 7.751387,
      "location": "FR",
      "location-full": "France",
      "gdpr": true
    },
    "49.284400,-123.108885": {
      "latitude": 49.2844,
      "longitude": -123.108885,
      "location": "CA",
      "location-full": "Canada"
    }
  },
  "throttle-acquired": 3,
  "throttle-available": 962
}