Understanding the API response - data definitions

Parsing the response, and interpretation of fields/attributes.

Once you have made your first API call, read on to understand the data expressed in the HTTP 200 OK response.

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

Interpreting data fields

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 Name

Description

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.

isEuropeanUnion

Whether the IP is used in an EU member state.

l10n.currencyName

The 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.currencyCode

The 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.currencySymbol

The symbol for the currency, such as $, ¥, when written in Latin script.

l10n.langCodes

An 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.countryName

The short-form colloquially-used name of the country, e.g., "United States" but not "United States of America."

locationData.countryCode

The two-letter country code (ISO 3166-1).

locationData.stateName

The 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.stateCode

The ISO code of the state or province name (see above). May be empty for smaller nations that don't have such subdivisions.

locationData.cityName

The major city closest to the geo-coordinates described below.

locationData.cityGeonamesId

The unique ID of the city as defined in the Geonames.org database.

locationData.lat, locationData.lng

The approximate latitude and longitude based on statistical models.

locationData.tz

The timezone in tzdata string format widely supported in date and time packages of programming languages.

locationData.continentCode

The 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).

satellite

An optional attribute that only exists if this IP belongs to a known satellite internet systems such as Starlink by SpaceX or Viasat.

satellite.provider

The name of the satellite internet provider, e.g "SpaceX Starlink".