REST API Reference

Introduction

We’ve introduced a REST API to allow you to leverage GIS Cloud’s features in your own apps, as well as help you integrate your data with our platform. This is an introductory guide; we also have a REST API reference.

If your client cannot produce all 4 HTTP verbs (GET, POST, PUT, DELETE) you can specify them using the _method parameter in the URL, e.g. https://api.giscloud.com/1/maps.json?_method=POST

In the examples we use curl, a useful command line utility that can produce all 4 HTTP verbs, making it useful for testing REST API’s. You can use it for trying out our API in order to get a feel for what kind of responses you need to parse, etc. On Linux you can install it via the system’s package manager, on Mac OS X it’s probably already installed on your machine, and on Windows you can download it from the project’s download page.

When it comes to actually using our API, you can of course use any HTTP client or library of your choice.

The information contained on this page is valid for the entire API. For details regarding specific API calls, see the REST API reference.

Protocols

secured: https://api.giscloud.com/

GIS Cloud API uses and requires HTTPS to help guarantee confidentiality, authenticity, and integrity. HTTPS provides a stronger guarantee that a client is communicating with the real API and receiving back authentic contents. It also enhances privacy for applications and users using the API.

Versioning

The version is a mandatory part of all requests.

set the version through the URL: .../<version>/...
or set the version through a request header: API-Version: <version> If both are used, the version in the URL has priority.

API Keys

Don’t authenticate over HTTP

Keys and tokens should only be used over an HTTPS connection. Using a key or token over HTTP is susceptible to eavesdropping. This puts your key/token (and through this, your data) at risk.

Please store it safely. If the API is accessed with your key through a non secure connection you’ll get a warning in your email.

authorize through a request param: api_key=<API_KEY>
authorize through a request header: API-Key: <API_KEY>

If both are used, the key sent through the URL has priority.

Key in URL Example

curl "https://api.giscloud.com/1/maps.json?api_key=d41d8cd98f00b204e9800998ecf8427e"

Key in Header Example

curl -H "API-Key: d41d8cd98f00b204e9800998ecf8427e" https://api.giscloud.com/1/maps.json

Creating an API key

An API key is a 32 character long secret word that enables you to access your private data and maps through the API.

It can be created through the GIS Cloud Application. After logging in, click on “My Account” on the top right of the screen. Choose the “API Access” tab, and under the “API Keys” heading, click “Add key”.

Format

Supported format for all API calls is 'json'.

You can specify a format by appending .json to the url or by setting the Content-Type header.

Format over Content-Type header: application/json.

If both are used, the format sent through the URL has priority.

Example with URL

curl https://api.giscloud.com/1/maps.json

Example with Content-Type header

$ curl -H "Content-Type: application/json" https://api.giscloud.com/1/maps.json

Pagination

When requesting large lists of resources, it helps to receive them in chunks instead of one, possibly enormous, list. With the page and perpage parameters, you can choose the size of pages that will be received, as well as which page you currently want.

Example

https://api.giscloud.com/1/maps.json?perpage=3

To view the seventh page, add the page parameter:

https://api.giscloud.com/1/maps.json?perpage=3&page=7

Sorting

Lists of resources can be sorted by any attribute using the order_by query parameter. Set order_by to the desired attribute, and (optionally) add the sorting direction, to have the list sorted.

For example, sorting maps by name looks like this:

https://api.giscloud.com/1/maps.json?order_by=name

Sorting by name in descending order looks like this:

https://api.giscloud.com/1/maps.json?order_by=name:desc

Maps

The Map object

Attributes

idNumberReadonlyExpandableMap id
nameStringRequiredMap name
ownerUserObjectExpandableMap owner object. This value only appears if the expand parameter contains the key 'owner'
epsgNumberEPSG map projection code
proj4StringProj4 map projection
unitsStringMap units (meter, foot or foot_us)
maxzoomNumberMaximum zoom
bgcolorStringMap background color
modifiedNumberLast time map was modified (UNIX timestamp)
accessedNumberLast time map was accessed (UNIX timestamp)
createdNumberTime when map was created (UNIX timestamp)
visitedNumberNumber of map views
descriptionStringMap description
archivedNumberIs map archived (0 or 1)
resourceResourceObjectExpandableMap resource object
permissions|Array of permissions|ExpandableShows current user's permissions on this resource: READ, EDIT, SHARE, INSERT_MDC, UPDATE_MDC, OWNER
optionsArray of optionsExpandableList of options tied to this resource. This value only appears if the expand parameter contains the key 'options'

Map object

{
   "id":"1198",
   "name":"City of Zagreb",
   "owner":{
      "id":"2",
      "username":"test"
   },
   "epsg":"900913",
   "active":"1",
   "copyright":"",
   "proj4":"+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0 +k=1.0 +units=m +nadgrids=@null +no_defs",
   "units":"meter",
   "maxzoom":"0",
   "bgcolor":"#ff0000",
   "modified":1602773958,
   "accessed":1602773958,
   "created":1593945880,
   "description":"",
   "units_proj4":"meter",
   "visited":"302",
   "resource_id":"14124",
   "measure_unit":"meter",
   "archived":"f",
   "visible":"t",
   "resource":{
      "id":"14124",
      "type":"5",
      "location":null,
      "target_resource_id":"1198",
      "owner_id":"2",
      "parent_id":null,
      "payment_subscription_id":null,
      "payment_id":null,
      "payment_id_obs":null,
      "archived":"0",
      "disabled":null,
      "created":"1593945880",
      "modified":"1593945880"
   },
   "permissions":[
      "OWNER"
   ],
   "bounds":"{\"xmin\":0,\"xmax\":0,\"ymin\":0,\"ymax\":0}"
}

List all maps

GEThttps://api.giscloud.com/1/maps.json

Get list of all maps readable by current user. Read access on a resource is allowed to all users or groups that have reading permissions (or higher) on that resource. Granting reading permissions on a resource to the anonymous user makes that resource publicly readable.

Query Parameters

Attribute name	Description
type	Filter by visibility: 'public', 'private', 'shared' or 'private,shared'
perpage	Number of results per page to display (Default: 100, Maximum: 1000)
page	Page number to display
order_by	Order by, format '{created\|modified\|created}:[asc\|desc]' E.g. order_by=accessed:desc
expand	Expand by 'owner', 'options' and 'permissions'
nototal	Total of results is not counted and displayed; improves response time; used for getting the response faster
query_on	Fields on which the query will be performed
query	Search query

Responses

Code	Description
200	Operation successful

Code	Description
200	Operation successful
403	Action forbidden
404	Resource not found

Code	Description
{MAP_ID}	Map ID
{FORMAT}	Using this parameter you can choose image format, it can be in 'jpg' or 'png' for images or 'iframe' for an interactive map.

Attribute name	Default	Description
phender	true	Starts the rendering engine
timestamp		Date/time of creation or modification.
width	256	Image width in pixels.
height	256	Image height in pixels.
layerlist	false	Set layerlist to visible.
bounds		Set bounds of rendered map. E.g. bounds=1674429.541,5684163.171,1876223.296,5816093.482
download	false	Downloads the rendered map
numscale	false	Set scale number, e.g. numscale=20000
invalidate	false	Invalidate cache
justgenerate		Just generate the image without saving
saveto		Set path to save image

Attribute name	Default	Description
toolbar	false	Set toolbar to visible.
layerlist	false	Set layerlist to visible.
popupus	false	Enable info popups in iframe when feature is selected.
layer_id		Set layer id.
feature_id		Set feature id.
bounds		Set bounds of rendered map.
width	100%	Set width of iframe
height	100%	Set height of iframe
visibility		Set visible layers, e.g. visibility=1011,2121,1543
expressions		Set visible expressions for a layer
f		Set features field to zoom into
v		Set the features field value
numscale		Set scale number
layerlist_expanded		Set expanded layerlist visible
scalebar		Set scalebar visible
noattrib		Sets noattrib class, removes attribution from the map
noctrl		Sets noctrl class, removes controllers from the map
no3d		Disables hardware-accelerated CSS 3D transforms for positioning
lockzoom		Disables zoom
style		Sets the css file to use

Code	Description
{MAP_ID}	Map ID
{INIT}	Do map cache reinitialization. Possible values are: 1 and 2

Code	Description
{LAYER_ID}	Layer ID
{FORMAT}	Using this parameter you can choose image format, it can be 'iframe' for an interactive map.

Code	Description
200	Operation successful + exported file
404	Resource not found

Attribute name	Description
geometry	Format in which geometry will be packed. Possible values: 'geojson', 'wkt', 'kml' and 'gml'.
epsg	EPSG code for the output projection. if not specified default map projection is used.
proj4	Proj4 string for the output projection. Alternative to the epsg parameter.

Code	Description
{LAYER_ID}	Layer ID
{FEATURE_ID}	Feature ID
{ATTRIBUTE_NAME}	Name of the attribute which contains media files; separate multiple files with commas
{FILE_NAME}	Attached file name

Attribute name	Description
expand	Expand by 'count'
only_spatial	Get only spatial tables
only_non_spatial	Get only non-spatial tables

Code	Description
200	Operation successful + exported CSV file
404	Resource not found

Attribute name	Description
query	Value to be searched
fields	List of layer IDs and layer attributes to include in search, format: {layer_id}~{field1},{field2},...~[{field1:DESC},---][;{layer_id}...]
x	Longitude or easting of the location
y	Latitude or northing of the location
perpage	Number of results per page to display (Default: 100, Maximum: 1000)
page	Page number to display
replace_special_chars	Replace special letters: 'å' => 'a', 'ä' => 'a', 'ö' => 'o', 'č' => 'c', 'ć' => 'c', 'đ' => 'd', 'dž' => 'dz', 'š' => 's', 'ž' => 'z'; case-insensitive
address_layer	Address layer ID to be included in the search
columns_meta	Include column's meta data

Attribute name	Description
perpage	Number of results per page to display Default: 100 Maximum: 1000
page	Result list offset for paginating
expand	A comma-seperated list of special resource object properties which can be expanded in the response object Expand options: "options"

Parameter name	Description
name	Name of the new layer
size	Buffer size
units	Units for the size param (meter, kilometer, mile, degree); optional (defaults to meter)
merge_geom	Group all geometry together; optional (defaults to true)
border_width	Width of the new layer’s features polygon border; accepts values 1-4; optional (defaults to 1)
border_color	An RGB color string for the new layer’s features polygon border color; optional (defaults to 0,0,0)
fill_color	An RGB color string for the new layer’s features polygon fill color; optional (defaults to 255,255,255)

Code	Description
201	Operation successful + Response header: location of the newly created layer (1/maps/{MAP_ID}/layers/{LAYER_ID})
404	Resource not found

Code	Description
{RESOURCE_ID}	Resource ID, can be of the map, layer, datasource etc.
{SHARE_ID}	ID of specific permission for resource

Code	Description
201	Operation successful + a URL to the newly created resource in the Location header of the response
404	Resource not found

Code	Description
201	Operation successful + URL to the newly created resource in the Location
404	Resource not found