Layers · Fulcrum Learning Portal

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

Endpoints

Method	Endpoint	Description	Example
GET	/api/v2/layers.json	Fetch all layers.	Get All
GET	/api/v2/layers/:id.json	Fetch a single layer.	Get Single
POST	/api/v2/layers.json	Create a new layer (GeoJSON & XYZ only).	Create
PUT	/api/v2/layers/:id.json	Update a single layers.	Update
DELETE	/api/v2/layers/:id.json	Delete a single layer.	Delete

Query Parameters

Parameter	Type	Description
page	integer	The page number requested.
per_page	integer	Number of items per page. By default, all requests are paginated to the maximum value of 20,000 items per request.

Properties

Property	Type	Required	Readonly	Description
name	string	yes	no	The name of the layer.
type	string	yes	no	The layer type (geojson, xyz).
source	string	yes	no	The layer source.
description	string	no	no	Optional layer description.
bounds	array	no	yes	The layer bounds.
center	number	no	yes	The layer center.
maxzoom	number	no	yes	The layer maximum zoom.
minzoom	number	no	yes	The layer minimum zoom.
access_token	string	yes	no	The layer access token.
id	string	no	yes	The id of the layer.
created_at	string	no	yes	Timestamp when the layer was created.
updated_at	string	no	yes	Timestamp when the layer was last updated.
file_size	number	no	yes	The file size (for mbtiles).

Validations

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

Property	Type	Description	Example
name	string	The name of the layer.	`"USGS Topo"`
type	string	The layer type (geojson, xyz).	`"xyz"`
source	string	The layer sourc (URL or inline GeoJSON).	`"http://basemap.nationalmap.gov/arcgis/rest/services/USGSTopo/MapServer/tile/{z}/{y}/{x}"`

Example validation response if type is not included:

{
  "layer": {
    "errors": {
      "type": ["must be one of xyz, geojson"]
    }
  }
}

Notes

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.

Response

{
  "layer": {
    "name": "USGS Topo",
    "description": "USGS Topo Base Map - Primary Tile Cache (http://viewer.nationalmap.gov/example/services/serviceList.html)",
    "source": "http://basemap.nationalmap.gov/arcgis/rest/services/USGSTopo/MapServer/tile/{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
  }
}

Examples

Get all Layers

cURL

Python

JavaScript

Ruby

curl --request GET 'https://api.fulcrumapp.com/api/v2/layers.json' \
--header 'Accept: application/json' \
--header 'X-ApiToken: {token}'

from fulcrum import Fulcrum
fulcrum = Fulcrum('{token}')

layers = fulcrum.layers.search()

for layer in layers['layers']:
  # print(layer)
  print(layer['name'])

const { Client } = require('fulcrum-app');
const client = new Client('{token}');

client.layers.all()
  .then((page) => {
    page.objects.forEach(layer => {
      // console.log(layer);
      console.log(layer.name);
    });
  })
  .catch((error) => {
    console.log(error.message);
  });

# Not currently supported

Get a single Layer by ID

cURL

Python

JavaScript

Ruby

curl --request GET 'https://api.fulcrumapp.com/api/v2/layers/:id.json' \
--header 'Accept: application/json' \
--header 'X-ApiToken: {token}'

from fulcrum import Fulcrum
fulcrum = Fulcrum('{token}')

layer = fulcrum.layers.find('{id}')

print(layer['layer'])

const { Client } = require('fulcrum-app');
const client = new Client('{token}');

client.layers.find('{id}')
  .then((layer) => {
    console.log(layer);
  })
  .catch((error) => {
    console.log(error.message);
  });

# Not currently supported

Create a new Layer

cURL

Python

JavaScript

Ruby

curl --request POST 'https://api.fulcrumapp.com/api/v2/layers.json' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-ApiToken: {token}' \
--data '{
  "layer": {
    "name": "USGS Topo",
    "type": "xyz",
    "source": "http://basemap.nationalmap.gov/arcgis/rest/services/USGSTopo/MapServer/tile/{z}/{y}/{x}"
  }
}'

from fulcrum import Fulcrum
fulcrum = Fulcrum('{token}')

obj = {
  "layer": {
    "name": "USGS Topo",
    "type": "xyz",
    "source": "http://basemap.nationalmap.gov/arcgis/rest/services/USGSTopo/MapServer/tile/{z}/{y}/{x}"
  }
}

layer = fulcrum.layers.create(obj)
print(layer['layer']['id'] + ' has been created!')

const { Client } = require('fulcrum-app');
const client = new Client('{token}');

const obj = {
  "name": "USGS Topo",
  "type": "xyz",
  "source": "http://basemap.nationalmap.gov/arcgis/rest/services/USGSTopo/MapServer/tile/{z}/{y}/{x}"
};

client.layers.create(obj)
  .then((layer) => {
    console.log(layer.id + ' has been created!');
  })
  .catch((error) => {
    console.log(error.message);
  });

# Not currently supported

Update a Layer

cURL

Python

JavaScript

Ruby

curl --request PUT 'https://api.fulcrumapp.com/api/v2/layers/:id.json' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-ApiToken: {token}' \
--data '{
  "layer": {
    "name": "USGS Topo",
    "description": "USGS Topo Base Map - Primary Tile Cache",
    "type": "xyz",
    "source": "http://basemap.nationalmap.gov/arcgis/rest/services/USGSTopo/MapServer/tile/{z}/{y}/{x}"
  }
}'

from fulcrum import Fulcrum
fulcrum = Fulcrum('{token}')

obj = {
  "layer": {
    "name": "USGS Topo",
    "description": "USGS Topo Base Map - Primary Tile Cache",
    "type": "xyz",
    "source": "http://basemap.nationalmap.gov/arcgis/rest/services/USGSTopo/MapServer/tile/{z}/{y}/{x}"
  }
}

layer = fulcrum.layers.update('{id}', obj)
print(layer['layer']['id'] + ' has been updated!')

const { Client } = require('fulcrum-app');
const client = new Client('{token}');

const obj = {
  "name": "USGS Topo",
  "description": "USGS Topo Base Map - Primary Tile Cache",
  "type": "xyz",
  "source": "http://basemap.nationalmap.gov/arcgis/rest/services/USGSTopo/MapServer/tile/{z}/{y}/{x}"
};

client.layers.update('{id}', obj)
  .then((layer) => {
    console.log(layer.id + ' has been updated!');
  })
  .catch((error) => {
    console.log(error.message);
  });

# Not currently supported

Delete a Layer

cURL

Python

JavaScript

Ruby

curl --request DELETE 'https://api.fulcrumapp.com/api/v2/layers/:id.json' \
--header 'Accept: application/json' \
--header 'X-ApiToken: {token}'

from fulcrum import Fulcrum
fulcrum = Fulcrum('{token}')

fulcrum.layers.delete('{id}')
print('{id} has been deleted!')

const { Client } = require('fulcrum-app');
const client = new Client('{token}');
  
client.layers.delete('{id}')
  .then((layer) => {
    console.log('{id} has been deleted!');
  })
  .catch((error) => {
    console.log(error.message);
  });

# Not currently supported