How It Works
Using the REQUEST function it’s possible to fetch external data over HTTP from your Data Events script. It can be combined with the other functions to create very dynamic forms that populate information on-demand from external sources. It contains the necessary options to perform any HTTP request, including support for PUT, POST, etc and custom headers.
// This example looks up the place name from OpenStreetMap when the location changes and fills in a text
// field with the place name. Replace 'place_name' below with a text field on your form.
ON('change-geometry', function(event) {
var options = {
url: 'https://nominatim.openstreetmap.org/search/' + LATITUDE() + ',' + LONGITUDE() + '?format=json&polygon=1&addressdetails=1'
}
REQUEST(options, function(error, response, body) {
if (error) {
ALERT('Error with request: ' + error)
} else {
var data = JSON.parse(body)
if (data.length) {
SETVALUE('place_name', data[0].display_name)
}
}
})
});
A basic example of using Request
change-geometry is fired when a record's geometry changes. With the release of Lines and Polygons, the latitude and longitude of a record may be null while the GEOMETRY of a record contains a valid Polygon or Linestring.
change-geometry is fired when a record's geometry changes. With the release of Lines and Polygons, the latitude and longitude of a record may be null while the GEOMETRY of a record contains a valid Polygon or Linestring.
Tip: You should use the data name of the fields that you want to populate. The body value is always a string, so if you want to parse it as JSON you’ll have to use JSON.parse like in the above example.
Troubleshooting
If you are having difficulty determining what the data is on your API you can use something like https://requestbin.com. This works great for inspecting the raw data.
CORS and Web Browser Support
To work in the web browser, URLs fetched using REQUEST require HTTPS & CORS. This is not a limitation of Fulcrum - it’s just the way modern web browsers work. Since Fulcrum is hosted on a secure website, all requests made from the site must also be secure and respond with the proper headers required by the browser. If you encounter CORS errors when trying to use an API with the REQUEST function, we recommend contacting the API provider and asking them to add CORS support to their API. As a last resort, you can use a CORS proxy to proxy requests to URLs that don’t support it. CrossOrigin.me is a freely hosted CORS proxy. Note: crossorigin.me is not a Fulcrum service.
Examples
You can view the CARTO Point-in-Polygon example for more insight into using APIs. We will be coming out with more in the next few weeks!