Quick Start on AWS

Signup

First off, subscribe to the Fastah 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.

You can make your first API call once you've obtained your API key.

Make an API call

There are two ways of building a request URL. The first style below requests information about the specified IP address and is recommended. The second style lets the Fastah API backend auto-detect the client's public IP address and is helpful for client-side browser deployments that will make CORS requests.


# Requests information on a specific IP address - RECOMMENDED
curl \
        -X GET "https://ep.api.getfastah.com/whereis/v1/json/98.97.16.1" \
        -H "Fastah-Key: {user.fastahIPlocationDemoKey}" 
        
        
# Auto-detect caller IP, useful for client-side JavaScript in the browser
curl \
        -X GET "https://ep.api.getfastah.com/whereis/v1/json/auto" \
        -H "Fastah-Key: {user.fastahIPlocationDemoKey}"

📘
Get your key
Make sure to configure Fastah-Key with your API key from the Fastah Developer Console.

Assuming a valid API key was used and authorization went smoothly, you should see a JSON response that looks as follows.

A sample HTTP 200 OK 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"
  }
}

📘
Understanding the response
The data definitions for the JSON response are explained on the Understanding the Response page

Integration with a front-end (JavaScript) - Not recommended

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': '{user.fastahIPlocationDemoKey}'}
        })
  .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.