Getting started with the FOAM API

This document provides details on how to make authenticated requests to the FOAM REST API to obtain data to produce various web maps shown below.

Thank you Will Carter for writing these examples!

Metamask and Rinkeby

You will need Metamask installed in your Chrome browser.

Next, you will need to use the Rinkeby Faucet to add funds to your Rinkeby wallet.

When using the Spatial Index beta, make sure you are on the Rinkeby Test Network.

Obtain authentication for the FOAM REST API

The FOAM REST API requires a header authorization key/value pair for each request.

Follow the this tutorial to obtain the Bearer auth string value:

The Bearer string will be similar to: 

1
Bearer fxtguifkduUxMiJ9.eyJkYXQdrceveM5NTFmMhSc8mHjvwph9eUOLX8vGgt6cbkqdlrzqtvw...

Send a test authenticated API request with Postman

  1. Install Postman a REST API utility
  2. Download the swagger.json definition of the FOAM REST API. This definition file can then be imported into Postman, which will provide easy access ot all the FOAM API endpoints. Download here - if the link doesn’t work go to the swagger link to the left and get the latest link.
  3. Import swagger.json into Postman to gain access to all the FOAM API endpoints (see screengrab below).

  4. Double click the https://api-beta.foam.space/beacon?lat_min=&lon_min=&lat_max=&lon_max=&zoom= API method and replace the GET url with one that contains actual bounding box coordinates, for example: 

    1
    https://api-beta.foam.space/beacon?lat_min=-74.024677&lon_min=-73.923054&lat_max=40.695998&lon_max=40.802245

  5. Add an authorization key with the Bearer auth string from the Authorization step above (see screengrab below).

  6. Send test request.

Find a bounding box

bboxfinder is a useful utility for finding a Latitude/Longitude bounding box that matches your geographic area of interest.

Note, when sending a GET /beacon request to the FOAM API, use the latitude/longitude values of your area of interest’s bounding box.

  • lat_min = smallest latitude value
  • lat_max = largest latitude value
  • lon_min = smallest longitude value
  • lon_max = largest longitude value

Example Maps

Leaflet

This is an example of a simple Leaflet.js map at displays FOAM CSC data by calling the API. The example uses the latlon-geohash library for geohash to latitude/longitude datapoint conversion and axios for making REST calls to the FOAM API.

FOAM REST API request: 

1
2
3
4
5
GET /beacon
https://api-beta.foam.space/beacon?lat_min={{lat_min}}&lon_min={{lon_min}}&lat_max={{lat_max}}&lon_max={{lon_max}}&zoom={{zoom}}

Example request:
https://api-beta.foam.space/beacon?lat_min=-105.154953&lon_min=39.580819&lat_max=-104.646835&lon_max=39.941857

There are many different Leaflet basemaps available.

Mapbox.GL

This is an example of a simple Mapbox.GL map at displays FOAM CSC data by calling the API. The example uses the latlon-geohash library for geohash to latitude/longitude datapoint conversion and axios for making REST calls to the FOAM API.

FOAM REST API request: 

1
2
3
4
5
GET /beacon
https://api-beta.foam.space/beacon?lat_min={{lat_min}}&lon_min={{lon_min}}&lat_max={{lat_max}}&lon_max={{lon_max}}&zoom={{zoom}}

Example request:
https://api-beta.foam.space/beacon?lat_min=-105.244904&lon_min=-104.648895&lat_max=39.515695&lon_max=39.985538

Custom markers

Similar to the example above but with a different base map and custom CSC markers.

FOAM REST API request: 

1
2
3
4
5
GET /beacon
https://api-beta.foam.space/beacon?lat_min={{lat_min}}&lon_min={{lon_min}}&lat_max={{lat_max}}&lon_max={{lon_max}}&zoom={{zoom}}

Example request:
https://api-beta.foam.space/beacon?lat_min=-11.030273&lon_min=27.202148&lat_max=35.38905&lon_max=58.950008

Data popup on hover

This example illustrates how to add a marker popup on mouse hover of a point.

FOAM REST API request: 

1
2
3
4
5
GET /beacon
https://api-beta.foam.space/beacon?lat_min={{lat_min}}&lon_min={{lon_min}}&lat_max={{lat_max}}&lon_max={{lon_max}}&zoom={{zoom}}

Example request:
https://api-beta.foam.space/beacon?lat_min=-74.024677&lon_min=-73.923054&lat_max=40.695998&lon_max=40.802245

Example CSC search implementation. Searches that will find matched names: “Denver2”, “London”, “ParisFoamBeta1”, “Marriott hotel” or any other beacon name.

FOAM REST API requests: 

1
2
3
4
5
6
7
8
9
GET /search
https://api-beta.foam.space/search?offset={{offset}}&query={{query}}
https://api-beta.foam.space/search?query=London123

then:

GET /beacon/{address}
https://api-beta.foam.space/beacon/:address
https://api-beta.foam.space/beacon/4ba12ad784ff4e596175cd3f38d04d582030561b