1. Introduction
  2. Protocols
  3. Versioning
  4. API Keys
    1. Creating an API key
  5. Format
  6. Pagination
  7. Sorting

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. http://api.giscloud.com/1/maps?_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

  • normal: http://api.giscloud.com/
  • secured: https://api.giscloud.com/

Some API methods work on HTTP and HTTPS and some only on HTTPS. HTTPS is used for secure access to private user data, while HTTP is usually used for public data where privacy is irrelevant.

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

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=<key>
  • authorize through a request header: API-Key: <key>

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

Key in URL:

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

Key in Header:

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

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 formats for almost all API calls are xml and json. The default format is xml.

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

Format over URL: xml, json Format over Content-Type header: text/xml, application/json

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

XML Example:

$ curl http://api.giscloud.com/1/maps.xml
$ curl -H "Content-Type: text/xml" http://api.giscloud.com/1/map

JSON Example:

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

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.

The URL will then look like this (using map listing as an example):

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

To view the seventh page, add the page parameter:

http://api.giscloud.com/1/maps?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:

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

Sorting by name in descending order looks like this:

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