Quick Start

Getting started with the Fastah IP Geolocation REST API

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 personal API key from the Fastah Developer Console.

Understanding the response

{
  "ip": "98.97.16.1",
  "isEuropeanUnion": false,
  "l10n": {
    "currencyName": "Dollar",
    "currencyCode": "USD",
    "currencySymbol": "$",
    "langCodes": [
      "en-US",
      "es-US",
      "haw",
      "fr"
    ]
  },
  "locationData": {
    "countryName": "United States",
    "countryCode": "US",
    "stateName": "New York",
    "stateCode": "NY",
    "cityName": "New York City, NY",
    "cityGeonamesId": 5128581,
    "lat": 40.71,
    "lng": -74.01,
    "tz": "America/New_York",
    "continentCode": "NA"
  },
  "satellite": {
    "provider": "SpaceX Starlink"
  }
}

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.

Field NameDescription
ip The IP address described in the response that follows. If you specified 'auto' in the REST API path, this also denotes the client's IP address observed by Fastah's server.
isEuropeanUnionWhether the IP is used in an EU member state.
l10n.currencyNameThe short-form colloquially-used currency name, e.g., "Dollar" but not "United States Dollar." Suitable for displaying to the user with accompanying context such as country name, flag, etc.
l10n.currencyCodeThe 3-letter ISO 4217 code for the currency. Suitable for programmers but only sometimes understood by end users. E.g. USD, EUR, or CNY.
l10n.currencySymbolThe symbol for the currency, such as $, Β₯, when written in Latin script.
l10n.langCodesAn array of language locales used in the country - used for text formatting or translation text lookups.

Always of length >= 1, _defaults to "en" _as a reasonable fallback when data is unavailable.
locationData.countryNameThe short-form colloquially-used name of the country, e.g., "United States" but not "United States of America."
locationData.countryCodeThe two-letter country code (ISO 3166-1).
locationData.stateNameThe short-form colloquially-used state or province name, e.g. "Massachusetts". This is the first-level administrative subdivision of a country, so this may be an empty string for smaller nations such as Singapore.
locationData.stateCodeThe ISO code of the state or province name (see above). May be empty for smaller nations that don't have such subdivisions.
locationData.cityNameThe major city closest to the geo-coordinates described below.
locationData.cityGeonamesIdThe unique ID of the city as defined in the Geonames.org database.
locationData.lat, locationData.lngThe approximate latitude and longitude based on statistical models.
locationData.tzThe timezone in tzdata string format widely supported in date and time packages of programming languages.
locationData.continentCodeThe continent code of the country, e.g "NA" for North America, or "AS" for Asia. Note that "EU" for Europe in this field does not imply membership of the European Union for which a separate attribute isEuropeanUnion exists (see above).
satelliteAn optional attribute that only exists if this IP belongs to a known satellite internet systems such as Starlink by SpaceX or Viasat.
satellite.providerThe name of the satellite internet provider, e.g "SpaceX Starlink".

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
  1. 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.

Run in Postman