Cookie consent

We use some essential cookies to make this website work. We'd like to set additional cookies to help us measure your experience when you view and interact with the website.

Cookie policy


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


Path parameters

apikeyYour API keyPCW45-12345-12345-1234X
ipaddressThe 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 request123.456.78.90

Querystring parameters

formatSets the format of the response, xml or json (default unless "application/xml" header is detected)format=json
identifierSpecifies 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 clientsidentifier=websiteA

Example request and response

Return geo information for the IP address of 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

validA true or false indicating whether the IP address is validtrue
ipaddressThe IP address123.456.78.90
cityThe GeoNames place of the approximate location associated with the IP addressDiss
cityidThe GeoNames place identifier2651214
subdivisionThe ISO 3166-2 name for the most specific subdivisionNorfolk
subdivisioncodeThe ISO 3166-2 code for the most specific subdivisionNFK
countryThe ISO 3166-1 country nameUnited Kingdom
countrycodeThe ISO 3166-1 two-letter country codeGB
continentThe continent: Africa, Antarctica, Asia, Europe, North America, Oceania or South AmericaEurope
continentcodeThe continent code: AF, AN, AS, EU, NA, OC or SAEU
postcodeA postal code fragment of the approximate location associated with the IP addressIP21
latitudeThe ETRS89 latitude52.3652
longitudeThe ETRS89 longitude1.2355
timezoneThe IANA time zoneEurope/London
euA true or false indicating whether the country is a member state of the European Unionfalse

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.