Layers API

The Layers API gives you access to the map layers within your Fulcrum account.


namestringyesnoThe name of the layer.
typestringyesnoThe layer type (fulcrum, xyz, tilejson, geojson, mbtiles, wms, feature-service).
sourcestringyesnoThe layer source.
descriptionstringnonoOptional layer description.
boundsarraynoyesThe layer bounds.
centernumbernoyesThe layer center.
maxzoomnumbernoyesThe layer maximum zoom.
minzoomnumbernoyesThe layer minimum zoom.
access_tokenstringyesnoThe layer access token.
idstringnoyesThe id of the layer.
created_atstringnoyesTimestamp when the layer was created.
updated_atstringnoyesTimestamp when the layer was last updated.
file_sizenumbernoyesThe file size (for mbtiles).


The following properties must be included in order to create/update a layer object in our system. Any validation errors will return a 422 and an object with a list of validation errors.

Required Properties

namestringThe name of the layer."USGS Topo"
typestringThe layer type (fulcrum, xyz, tilejson, geojson, mbtiles, wms, feature-service)."xyz"
sourcestringThe layer sourc (URL or inline GeoJSON)."{z}/{y}/{x}"

Example validation response if type is not included:

  "layer": {
    "errors": {
      "type": [
        "must be one of fulcrum, xyz, tilejson, geojson, mbtiles, wms, feature-service"


  • The entire layer object is required when making an update. Omitting fields with existing data will result in data loss! The typical workflow for updating an existing layer is to fetch the layer object, modify it, and then submit the PUT request.
  • For more information on uploading MBTiles files, please see AWS Interactions

Sample Response

  "layer": {
    "name": "USGS Topo",
    "description": "USGS Topo Base Map - Primary Tile Cache (",
    "source": "{z}/{y}/{x}",
    "bounds": null,
    "center": null,
    "maxzoom": null,
    "minzoom": null,
    "access_token": null,
    "id": "18e95686-b125-4baa-a263-b9bef2f9fee7",
    "created_at": "2014-10-22T17:07:53Z",
    "updated_at": "2014-10-24T19:21:05Z",
    "type": "xyz",
    "file_size": 0

Here's an example of how to upload an MBTiles file in python

import requests
import json
import os


headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "x-apitoken": API_TOKEN

# Get the URL that we will upload our MBTiles file to
file_req_url = ""
file_res = requests.get(url=file_req_url, headers=headers)
put_url_json = json.loads(file_res.text)
put_url = put_url_json['file']['url']

# Load the MBTiles file
with open(
        os.path.dirname( __file__ ), 
    ), 'rb') as f:
    data =

# Put MBTiles file to AWS at the put_url
aws_response = requests.put(put_url,data=data)

# Make a layers object with "key" param instead of "source"
layers_json = {
    "layer": {
        "key": put_url_json['file']['key'],
        "type": "mbtiles",
        "name": "frankenlayer!"

layers_url = ''
final_req =, headers=headers, json=layers_json )