Using Data Shares With Fulcrum

Overview of Data Shares and Data Sharing Permissions in Fulcrum. (Intermediate)

Jacob Payne avatar
Written by Jacob Payne
Updated over a week ago

Getting Ready

We assume you’ve read the general data shares overview and related manual pages. We will build on top of that knowledge here.

This article focuses on the details related to consuming an existing data share and how to modify the URL to customize the data returned.

Note: When mentioning URLs below, variable sections are indicated {LIKE_THIS}. For instance https://web.fulcrumapp.com/shares/{ACCESS_TOKEN}.{FORMAT} , when filled in with real values, would look something like https://web.fulcrumapp.com/shares/a5b23def801cc4a9.csv . The curly braces and everything inside them are replaced with an actual value.

URL Format

When a share is enabled, it’s given a unique, 16 character, hexadecimal token which is used in the URL to access the App’s data. You can use this token to retrieve data in one of the following formats: csv, kml, geojson, or json.

The URL format is:

https://web.fulcrumapp.com/shares/{ACCESS_TOKEN}.{FORMAT}

KML Feed URL

The KML format has an additional URL you can use to refresh the data within Google Earth as you pan and zoom. The KML feed includes a KML network link to the regular KML data share URL. Google Earth takes care of re-fetching the data when the user changes the map. This allows the feed to be a real-time view of your App’s data.

The URL format is:

https://web.fulcrumapp.com/shares/{ACCESS_TOKEN}/feed

Accessing Repeatable Sections

The child records for the repeatable sections within an App are available through the data share URL by using the child query string parameter. The value for this parameter is the data_name of the Repeatable field in the App’s schema whose records you’re like. This is also true for nested Repeatable sections.

As an example, let’s imagine an App named Country Data which is used to collect information about houses in particular cities in various countries. So the Country Data App has a repeatable Section for Cities, which in turn has a repeatable section for Houses. The data names for the Cities and Houses repeatable sections would, by default, be cities and houses respectively. The query string parameter and value needed to access these datasets from the data share’s URL would be child=cities and child=houses.

Note: This child parameter is not applicable for the JSON format since the data for the child records is included with the root records.

Accessing Photos, Videos, and Signatures

Photos, video, and signatures for a shared App are shared as well.

The KML data share has image and video links embedded within it. When a record has photos, videos, or signatures, Google Earth will show them automatically.

The other data formats have the media IDs within the data. You can use these IDs and the URL formats below to retrieve the media.

  • The URL format for photos is:

https://web.fulcrumapp.com/shares/{ACCESS_TOKEN}/photos/{IMAGE_ID}  

  • The URL format for photo thumbnails is:

https://web.fulcrumapp.com/shares/{ACCESS_TOKEN}/photos/{IMAGE_ID}/thumbnail
  • The URL format for signatures is:

https://web.fulcrumapp.com/shares/{ACCESS_TOKEN}/signatures/{SIGNATURE_ID}
  • The URL format for signature thumbnails is:

https://web.fulcrumapp.com/shares/{ACCESS_TOKEN}/signatures/{SIGNATURE_ID}/thumbnails
  • The URL format to preview videos is:

https://web.fulcrumapp.com/shares/{ACCESS_TOKEN}/videos/{VIDEO_ID}
  • The URL format to preview videos with tracks is:

https://web.fulcrumapp.com/shares/{ACCESS_TOKEN}/videos/{VIDEO_ID}/play
  • The URL format for video thumbnails is:

https://web.fulcrumapp.com/shares/{ACCESS_TOKEN}/videos/{VIDEO_ID}/thumbnail
  • The URL format to download video tracks:

https://web.fulcrumapp.com/shares/{ACCESS_TOKEN}/videos/{VIDEO_ID}/track.{FORMAT}
  • The URL format to download all video tracks for an App:

https://web.fulcrumapp.com/shares/{ACCESS_TOKEN}/videos/tracks.{FORMAT}

Note: Video track formats include gpx, kml, geojson, and geojson?type=points.

Forcing SSL

Data share URLs are served over HTTPS. Accessing any of the data share URLs via HTTP will result in a 301 Moved Permanently redirect to the same path using the HTTPS protocol.

Query Params

Available parameters to query data shares. All of the parameters may be used together to filter the data for more accurate results. Parms are added to the end of the URL. The first param is lead with a ? and any additional params are lead with a  & 

URL format for query params:

https://web.fulcrumapp.com/shares/a5b23def801cc4a9.csv?project_id=12345&per_page=5000&page=2

assigned_to

  • String. Email address of a user who belongs to the organization owning the App. Returns only record assigned to this user. The @ sign must be URL encoded as %40. 

project_id

  • String. The project id for which to filter the records. Only records tagged with this project will be returned. 

bounding_box 

  • String. Default empty string. Bounding box of the records requested. Format should be: lat,long,lat,long (bottom, left, top, right). 

child

  • String. Return the child records of the Repeatable section with this data_name. Not applicable to the JSON format. Leaving this blank defaults to the root record level. fulcrum_id String. ID of the single record to return. When blank, it will return all applicable records. 

human_friendly

  • Boolean. Default false. When false, return the data_name values for the columns. When true, return the label values for the columns, or a more readable version of the system columns. Useful for displaying the data in a way that’s more natural for humans to read. Not applicable to the JSON format. 

newest_first

  • Including this parameter with any non-blank value will return records ordered by last updated time in descending order. Leaving this parameter blank or omitting it completely will return records ordered by last update time in ascending order. Using this for child records will sort by the root record’s last updated time. page Integer. Default 0. Number of the page selected. 

page

  • Integer. Default 1. Which page of records to fetch. For use with per_page.

per_page

  • Integer. Default and hard cap of 20000. Number of records to return per page. 

skip_system_columns

  • Boolean. Default false. When false, include user columns and system columns added by Fulcrum. When true, skip Fulcrum’s system columns and only include user-defined columns. Useful for quickly creating a web map that shows only user-generated data. Not applicable to the JSON format.

updated_since

  • Integer. Date since epoch in seconds: 2012-04-24 15:05:22 -0400 = 1335294322. Leaving this blank will query against all of the records. Using this for child records will look at the root record’s last updated time. 

Did this answer your question?