ipaddress

This endpoint provides geolocation information for a given public IP address. It includes GeoLite2 data created by MaxMind and returns the approximate location, country, continent, latitude, longitude, timezone, and whether the location is within the European Union. These details can be used for several purposes, such as presetting a user's country on an address lookup form or providing them with location-specific content.

IP address geolocation is inherently imprecise and should not be used to identify a particular address.

Request URL

GET https://ws.postcoder.com/pcw/{apikey}/ipaddress/{ipaddress}

Path parameters

Parameter	Description	Example
`apikey`	Your API key	`PCW45-12345-12345-1234X`
`ipaddress`	The URL-encoded public IP address that you wish to query; when not supplied, the endpoint will try to detect and use the public IPv4 address of the client making the request	`123.456.78.90`

Querystring parameters

Parameter	Description	Example
`format`	Sets the format of the response, xml or json (default unless "application/xml" header is detected)	`format=json`
`identifier`	Specifies your own meaningful identifier for the request such as "websiteA" or "client123"; you can view usage for each identifier on the Identifier Usage page, which may be helpful when using your API key across multiple websites, apps or clients	`identifier=websiteA`

Example request and response

Return geo information for the IP address of 123.456.78.90:

GET https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/ipaddress/123.456.78.90

{
	"valid": true,
	"ipaddress": "123.456.78.90",
	"city": "Diss",
	"cityid": "2651214",
	"subdivision": "Norfolk",
	"subdivisioncode": "NFK",
	"country": "United Kingdom",
	"countrycode": "GB",
	"continent": "Europe",
	"continentcode": "EU",
	"postcode": "IP21",
	"latitude": "52.3652",
	"longitude": "1.2355",
	"timezone": "Europe/London",
	"eu": false
}

Response fields

Field	Description	Example
`valid`	A true or false indicating whether the IP address is valid	true
`ipaddress`	The IP address	123.456.78.90
`city`	The GeoNames place of the approximate location associated with the IP address	Diss
`cityid`	The GeoNames place identifier	2651214
`subdivision`	The ISO 3166-2 name for the most specific subdivision	Norfolk
`subdivisioncode`	The ISO 3166-2 code for the most specific subdivision	NFK
`country`	The ISO 3166-1 country name	United Kingdom
`countrycode`	The ISO 3166-1 two-letter country code	GB
`continent`	The continent: Africa, Antarctica, Asia, Europe, North America, Oceania or South America	Europe
`continentcode`	The continent code: AF, AN, AS, EU, NA, OC or SA	EU
`postcode`	A postal code fragment of the approximate location associated with the IP address	IP21
`latitude`	The ETRS89 latitude	52.3652
`longitude`	The ETRS89 longitude	1.2355
`timezone`	The IANA time zone	Europe/London
`eu`	A true or false indicating whether the country is a member state of the European Union	false

Integration advice

URL encode all special characters (including /) in your request parameters with %xx encoding
Verify your request was successful by checking for an HTTP status code of 200; see all HTTP status codes with descriptions
When using your API key across multiple websites, apps or clients, set the identifier querystring parameter to a meaningful value such as "websiteA" or "client123"; you'll then be able to view these identifiers and the number of requests made by each one on the Identifier Usage page
Treat all response fields as optional

Credit cost

Each request costs 0.2 credits.

Buy a credit pack or set up a monthly plan to use with all Postcoder endpoints.