Skip to main content

Example: Where is the International Space Station (ISS)?

This example shows how to create an API that combines data from multiple web services.

info

If you are not familiar with RAW we recommend checking out our Getting started guide first. To use RAW, you need an account which you can create and use for free here.

info

If you want to try this example, you can deploy the following endpoint:

ISS location
Obtain the current location of the International Space Station by joining two web services.

Usage:

/examples/iss

The goal is to obtain the nearest location on Earth to the International Space Station. For this, we combine two existing APIs:

The resulting REST API returns a list of the couple of places the ISS is flying over.

For instance, at the time of development, a call would return:

[
  "Adrar, Mauritania"
]

Getting the ISS position​

Here's the API call to get the ISS location: http://api.open-notify.org/iss-now.json.

Here's an example response this service returns:

{
  "message": "success",
  "timestamp": 1675083740,
  "iss_position": {
    "longitude": "106.5087",
    "latitude": "38.2938"
  }
}

The message only includes GPS coordinates and does not explicitly states where the ISS is in the world. To find a named location, we need reverse geocoding of the ISS latitude and longitude.

Reverse Geocoding​

Many geocoding APIs are available. We use the OpenCage Geocoding API. This service requires an API key that is generated when creating an account. Both the API key and the coordinates have to be provided as query parameters, e.g.:

https://api.opencagedata.com/geocode/v1/json?key=<API_KEY>&q=<LATITUDE>,<LONGITUDE>

Latitude and longitude of the ISS are extracted from the former JSON record after it is downloaded and parsed with Json.InferAndRead.

let iss = Json.InferAndRead("http://api.open-notify.org/iss-now.json"),
    latitude = iss.iss_position.latitude,
    longitude = iss.iss_position.longitude,

Here's how to prepare the HTTP query to OpenCage and retrieve the result.

let //
    // ...
    //
    geoQuery = latitude + "+" + longitude, // a URL parameter required by the API
    key = Environment.Secret("opencagedata"), // the API key is stored as a secret
    httpQuery = Http.Get(
        "https://api.opencagedata.com/geocode/v1/json",
        args = [
            {"q", geoQuery},
            {"key", key},
            {"no_annotations", "1"} // no_annotations returns simpler data
        ]
    ),
    // etc.
    issGeoLoc = Json.InferAndRead(httpQuery, preferNulls = true)

The call returns a JSON record with lots of information. We need the location's name. It is found under field name formatted:

{
  "documentation": "https://opencagedata.com/api",
  ...
  "results": [
    {
      ...
      "formatted": "Adrar, Mauritania"
      ...
    }
  ],
  "status": {
    "code": 200,
    "message": "OK"
  },
  ...
}

Once issGeoLoc is populated with the geolocation data, the city name is easily retrieved from issGeoLoc.results.formatted.

Putting it all together​

Here's the full code of our service.

let
    iss = Json.InferAndRead("http://api.open-notify.org/iss-now.json"),
    latitude = iss.iss_position.latitude,
    longitude = iss.iss_position.longitude,
    geoQuery = latitude + "+" + longitude,
    key = Environment.Secret("opencagedata"),
    httpQuery = Http.Get(
        "https://api.opencagedata.com/geocode/v1/json",
        args = [
            {"q", geoQuery},
            {"key", key},
            {"no_annotations", "1"}
        ]
    ),
    issGeoLoc = Json.InferAndRead(httpQuery, preferNulls = true)
in
    issGeoLoc.results.formatted

Ready to try it out?

Register for free and start building today!

Otherwise, if you have questions/comments, join us on Discord!