Quick Start

Signup

First off, subscribe to the Fastah IP Geolocation API on AWS Marketplace. Once you pick a subscription plan and billing term, you will be redirected to the Fastah Developer Console to create an account and obtain an API key.

Once you have obtained your Fastah API key, make your first API call.

Make an API call

Use either of the following styles to look up a specific IP, or let the Fastah backend autodetect the client's public IP address.

curl \
        -X GET "https://ep.api.getfastah.com/whereis/v1/json/103.10.66.11" \
        -H "Fastah-Key: <<fastah-iplocation-demo-key>>" 
        
curl \
        -X GET "https://ep.api.getfastah.com/whereis/v1/json/auto" \
        -H "Fastah-Key: <<fastah-iplocation-demo-key>>"

📘

Get your key

Make sure to use your own API key from the developer console.

Understanding the response

{
  "ip": "208.116.147.1",
  "isEuropeanUnion": false,
  "l10n": {
    "currencyName": "Dollar",
    "currencyCode": "USD",
    "currencySymbol": "$",
    "langCodes": [
      "en-US",
      "es-US",
      "haw",
      "fr"
    ]
  },
  "locationData": {
    "countryName": "United States",
    "countryCode": "US",
    "cityName": "Boston, MA",
    "cityGeonamesId": 4930956,
    "lat": 42.36,
    "lng": -71.06,
    "tz": "America/New_York",
    "continentCode": "NA"
  }
}

Here are the key JSON properties you will need to parse. Note that due to the statistical models used for IP geo-location, all locations should be considered approximate.

Integration with a backend service

While integrating with a server back end, you will need to determine the visitor's public IP address so that it may be passed to the Fastah API.

The client's public IP address is obtained by inspecting the incoming HTTP request object or context - see your language's HTTP server handler API documentation.

Determine the public IP address

1. Inspect the X-Forwarded-For header - if present, extract the left-most value from the comma-separated list of IPs if it's present.

X-Forwarded-For: 2001:db8:85a3:8d3:1319:8a2e:370:7348

X-Forwarded-For: 203.0.113.195

X-Forwarded-For: 203.0.113.195, 70.41.3.18, 150.172.238.178

2. If the X-Forwarded-For header is absent, simply use the remote IP address with any colons (":") removed - that is split the host and port and use only the host value as the client IP address.

Steps 1 and 2 above are demonstrated below in a Go programming language snippet.

// Use the server handler's object to inspect remote IP address
clientIP := params.HTTPRequest.RemoteAddr
if strings.Contains(clientIP, ":") { // host:port splitting
    if splitIP, _, serr := net.SplitHostPort(clientIP); serr == nil {
		  clientIP = splitIP
		}
}
// Extract X-Forwarded-For imformation if present - and use it
fwdList := params.HTTPRequest.Header.Get("X-Forwarded-For")
if fwdList != "" {
    clientIP = fwdList
		// Extract left-most entry in the comma-seperated list
		leftmost := strings.Split(fwdList, ",")
		if len(leftmost) > 0 {
          // 
					clientIP = leftmost[0] 
		}
}
clientIP = strings.TrimSpace(clientIP)

Send the request

Simply append the client IP address as a string to the base URL, append the API key as the Fastah-Key HTTP header, and send the request.

url := 'https://ep.api.getfastah.com/whereis/v1/json/' + clientIP

Performance tips - back end

Reuse the same HTTP client for calls to the Fastah API end-point, so your HTTP connection doesn't have to be re-established every time.
It's highly recommended to enable HTTP/2 support in the client to minimize API latency across all requests, and request+response throughput is maximized between your client and Fastah's API systems.

Integration with a front-end (JavaScript)

If you wish to make the browser call the API using XHR or fetch via JavaScript, use the examples below.

The URL path ending with auto tells the Fastah API backend to auto-detect the client's IP address. This works well when the API call is made from the end user's browser (XHR/fetch) or app (iOS/Android/WebView), i.e., where the clients are expected to have a public, globally-routable IP address that the Fastah API backend can infer.

<script>
  // Fetch is the modern web-standard alternative to XHR
  // API path ends with 'auto' - auto-detect the client's public IP
  fetch('https://ep.api.getfastah.com/whereis/v1/json/auto', 
        { mode: 'cors',
          headers: {'Fastah-Key': '<<fastah-iplocation-demo-key>>'}
        })
  .then(response => response.json())
  .then(data => console.log(data));
</script>

<script>
  const xhr = new XMLHttpRequest();
  // API path ends with 'auto' - auto-detect the client's public IP
  const url = 'https://ep.api.getfastah.com/whereis/v1/json/auto';
  xhr.open('GET', url);
  xhr.setRequestHeader("Fastah-Key", '<<fastah-iplocation-demo-key>>')
  xhr.onreadystatechange = someHandler;
  xhr.send();
</script>

Performance tips - browser

Consider adding dns-prefetch in the HTML's head to make the API latency extra snappy. If you expect the API call to be made most of the time the page is loaded by the user, add preconnect too to initiate a network connection pre-emptively.

For more information, see the explanation on Mozilla Developer Network.

<head>
    <!-- Recommended link tags to turbo-charge Fastah API latency -->
    <link rel="dns-prefetch" href="https://ep.api.getfastah.com/">
    <link rel="preconnect" href="https://ep.api.getfastah.com" crossorigin>
    <!-- and all other head elements -->
</head>

Need More Help?

Drop us a line at [email protected] with any questions, bug reports, or training requests, or if you want to chat!

For Postman users

If you use the Postman API development tool, use the button below to open the collection in your workspace.