How to Use the API

What is an API?

The FHAB API service is a protocol for retrieving data from FHABs using URLs (that is, using HTTP over the web). Much like any webpage, URLs help locate and fetch certain resources, however with a web API, the focus is on fetching data rather than formatted webpages. Available URLs follow a certain protocol which makes it easier to generate different types of requests and interactions with the API service. It allows requests to be defined and parameterized through the URL structure. In turn, the API service reads and interprets the request, processes it, and returns the appropriate data.

In general, FHAB API follows the REST architectural style, which is a set of guidelines and constraints that promote consistency and interchangeability between different API services.

More:

Routes, endpoints, and requests

Routes have a structure which identify a particular type of request being made to the API, which may have dynamic parts where parameters can be defined. An endpoint is mostly synonymous with a route, but includes the HTTP request method. Though not in the case of FHAB API, which only handles data retrieval, the HTTP request method can change the action of the request.

For example, the URL to request the download of a raster is:

https://fhab-api.sfei.org/{product}/{composite}/{date}/{format}

The route is everything after the base URL (after https://fhab-api.sfei.org). Within the route, items are separated with a forward slash (/) and those items encased in curly brackets ({}) indicate parameters relevant to the request that need to be defined. For this example, the API needs to know the parameters of the raster being requested, which includes the data product, composite type, date, and format.

E.g. the completed route to download the cyano, 1-day pixel maximum raster for Aug 31, 2022 as a GeoTIFF file is:

https://fhab-api.sfei.org/cyano/1daymax/20220831/tiff

Making a request by constructing the appropriate route is like constructing a sentence. The parameters in the route fill in the information like words do in a sentence to convey meaning. The order of the words is important, as is which types of words appear, for the API to correctly interpret the request, but within the allowed structure there is freedom to convey many different requests by changing the parameters.

The above mainly describes GET requests, where all the parameters are encoded in the URL itself. Other type of requests (e.g. POST) can allow for the parameters to be encoded not in the URL but in the message body. (While not exactly RESTful, FHAB API interprets POST requests for data retrieval so as to allow parameters passing via the message body.)

Using the API

To use the API, simply make a request to an endpoint and await the response. If the response is successful (with HTTP response status code 200-299), it will return the data being requested. This data may formatted as JSON, CSV, raster, or zipfile, depending on the request made. If there was an error handling the request, the HTTP response status code will indicate an error (400-599) and the response text will contain the error message.

The API may be interfaced with by any number of scripting languages and libraries therein. For Python, the requests package is a popular option for handling HTTP requests. For JavaScript, the Fetch API is generally the easiest way. Curl is another popular option for scripting HTTP requests.


© San Francisco Estuary Institute 2026