Permalink
Fetching contributors…
Cannot retrieve contributors at this time
3807 lines (2916 sloc) 150 KB

#Warper API Documentation

Welcome to the documentation for the Warper API! MapWarper is a free application that assigns the proper geographic coordinates to scanned maps in image formats. Users can upload images, then assign ground control points to match them up with a base map. Once MapWarper warps or stretches the image to match the corresponding extent of the base map, it can be aligned and displayed with other maps, and used for digital geographic analysis. You can access all of the functionality through the API.

Table of Contents

Api-Endpoint2

/api/v1

Protocol

Both http and https calls work. If you call a https resource, then links within the JSON response should also have https protocols, if you call it via http then the links should be in http. Note that OAuth authentication is configured for https only.

Format

Where possible most output formats are in json-api format. Some creation and updating requests also require the json to be in this format.

JSON format

For more infomation about the JSON API format, please consult http://jsonapi.org/. Things to watch out for (compared to the previous warper API) the JSON API has data as a root array, and the data for each feature are in an attributes array. The format also allows the system to include relationships (for example, including the layers with each map) and also shows links to various resources and contains pagination meta information.

The GeoJSON is different in structure and also in that it encodes the geometry of features in GeoJSON format. It does not include relations or links or pagination information. For more information about the GeoJSON format see the GeoJSON site. http://geojson.org/

Authentication

Some calls do not require authentication. Some do, and some require the user to have the correct authorization.

Authentication for the MapWarper API is via an authentication token passed in a header. This can be obtained via Oauth via the postMessage browser API, or via email and login.

Alternatively the API can work via cookie also.

Authentication Token

To authenticate using an email and password to retrieve an authentication token.

Method Definition
POST /api/v1/auth/sign_in.json

Parameters

Name Type Description Required Notes
email string Email of the user required
password string Password of the user required

Curl Example*

curl -X POST http://mapwarper.net/api/v1/auth/sign_in.json -H "Content-Type: application/json" -d '{"user":{"email":"user@example.com","password":"userpassword"}}' -v

Response

A successful response returns the user as JSON in the data element and the authentication token in a meta element

{
  "data": {
    "id": "2",
    "type": "users",
    "attributes": {
      "login": "tim",
      "created_at": "2010-08-26T15:37:34.619Z",
      "enabled": true,
      "provider": null
    },
    "links": {
      "self": "http://mapwarper.net/api/v1/users/2"
    }
  },
  "meta": {
    "auth_token": "BSNSJK3939sbascsc"
  }
}

if unauthorized returns a 401 status with

{"error":"Invalid email or password."}

Sign out

To sign out which deletes the authentication token. Authentication is required.

Method Definition
DELETE /api/v1/auth/sign_out.json

Curl Example*

curl -X DELETE http://mapwarper.net/api/v1/auth/sign_out.json -H -H 'X-User-Token: longtoken' -H 'X-User-Id: 2' "Content-Type: application/json" -v

Response

A successful response returns a 200 OK status and an empty hash {}

An unsuccessful response returns a 422 unprocessable entity status and an empty hash {}

Validate Token

This is a call to check if an authentication token is still valid. (Signing in and out both reset tokens)

Method Definition
GET /api/v1/auth/validate_token.json

Parameters

Name Type Description Required Notes
email string Email of the user required
password string Password of the user required

Curl Example*

curl -X POST http://mapwarper.net/api/v1/auth/sign_in.json -H "Content-Type: application/json" -H 'Accept: application/json' -d '{"user":{"email":"user@example.com","password":"userpassword"}}' -v

Response

A successful response returns the user as JSON in the data element and the authentication token in a meta element

{
  "data": {
    "id": "2",
    "type": "users",
    "attributes": {
      "login": "tim",
      "created_at": "2010-08-26T15:37:34.619Z",
      "enabled": true,
      "provider": null
    },
    "links": {
      "self": "http://mapwarper.net/api/v1/users/2"
    }
  },
  "meta": {
    "auth_token": "longtoken"
  }
}

if unauthorized returns a 401 status with

{"error":"Invalid email or password."}

Using the authentication token

You can authentication via the token in two ways

  1. Recommended: setting X-User-Id and X-User-Token in the header
curl  -H 'X-User-Token: longtoken' -H 'X-User-Id: 2' -X GET http://mapwarper.net/api/v1/users/2.json -v
  1. Passing user_id and user_token as parameters (handy for GET requests)
curl  -X GET http://mapwarper.net/api/v1/users/2.json?user_id=2&user_token=longtoken -v

Oauth Authenticaton and Authentication Token

Instead of using an email and password, a user can login via OUath with Github, twitter, google, and Wikimedia Commons for example. This is the way a third party JavaScript application can work with OAuth and the warper

** Note: The Oauth path is /u/auth/{:provider} and not within the api namespace. This may change.

Method Definition
GET /u/auth/{:provider}

Parameters

Name Type Description Required Notes
privoder string Oauth Provider required one of "github", "mediawiki", "twitter", "osm "etc

The process uses the Browser postMessage API to communicate across windows.

See https://github.com/timwaters/warper_oauth_token_auth_demo for an example app that uses JToker Jquery library for authentication.

Example JS code:

// create popup window
var domain = 'https://mapwarper.net';
var myPopup = window.open(domain + '/u/auth/mediawiki?omniauth_window_type=newWindow&auth_origin_url=' + window.location.href, 'myWindow');

// periodical message sender
var messenger = setInterval(function() {
  var message = 'requestCredentials';
  //send the message and target URI
  myPopup.postMessage(message, domain);
}, 500);

// listen to response
window.addEventListener('message', function(event) {
  // the message listener get's triggered by any URL make sure it's the right one
  if (event.origin !== domain) return;
  clearInterval(messenger);
  console.log(event.data);
}, false);

The warper renders /app/views/devise/omniauth_external_window.erb.html

The following gets rendered when the user successfully allows the request:

var data;
window.addEventListener("message", function(ev) {
  if (ev.data === "requestCredentials") {
      data = {
       message: "deliverCredentials", 
       auth_token: 'longtoken', 
       uid: '1234', 
       id: '23',
       name: 'Username',
       email: 'Username@example.com',
       provider: 'mediawiki '
   }

    ev.source.postMessage(data, '*');
   window.close();
  }
});
function requestCredentials() {
  return data;
}

Then, using the id and the email from the message, API response can be crafted. See https://github.com/timwaters/warper_oauth_token_auth_demo for an example app.

Cookie Authentication

The API can also be authenticated with cookies (for example a user logged into the warper in the browser can call the API GET requests in the browser).

Curl Examples for Email and Password authentication and cookies

curl -X POST http://mapwarper.net/u/sign_in.json -H "Content-Type: application/json"  -H 'Accept: application/json' -d '{"user":{"email":"tim@example.com","password":"password"}}' -c cookie

if successful, returns logged in user as jsonapi

{
  "data": {
    "id": "2",
    "type": "users",
    "attributes": {
      "login": "tim",
      "created_at": "2010-08-26T15:37:34.619Z",
      "enabled": true,
      "provider": null
    }"links": {
      "self": "http://mapwarper.net/api/v1/users/2"
    }
  }
}

if unauthorized returns a 401 status with

{"error":"Invalid email or password."}

Example using the cookie:

curl -H 'Content-Type: application/json' -H 'Accept: application/json' -X GET http://mapwarper.net/api/v1/users/2.json -b cookie

Unauthorized calls may return

Status Response
402 (unauthorized) {"errors":[{"title":"Unauthorized","detail":"Unauthorized Request"}]}

Search for Maps

Method Definition
GET /api/v1/maps.json?query=london

Returns a list of maps that meet search criteria (where the title or description contains "london") No authentication required.

Parameters

Name values Type Description Required Notes
query string search query optional
field string specified field to be searched optional default is title
title string the title of the map optional default
description string the description of the map optional
publisher string the publisher optional
author string the author of the map optional
status string the status optional
sort_key the field that should be used to sort the results optional default is updated_at
title string the title of the map optional
updated_at string when the map was last updated optional default
created_at string when the map was created optional
status string the status of the map optional ordered by integer (see below)
sort_order string the order in which the results should appear optional default is desc
asc ascending order optional
desc descending order optional default
show_warped integer limits to maps that have already been warped optional
1 integer limits to maps that have already been warped optional
0 integer gets all maps, warped and unwarped optional default
format string specifies output format optional can also be passed in as extension, eg. maps.json
json string JSON format for maps optional default
geojson string GeoJSON format for maps optional simple array, not featurecollection
page integer the page number; use to get the next or previous page of search results optional
per_page integer number of results per page optional default is 50
bbox a comma-separated string of latitude and longitude coordinates a rectangle delineating the geographic area to which the search should be limited optional
operation string specifies how to apply the bounding box optional default is intersect
intersect string uses the PostGIS ST_Intersects operation to retrieve warped maps whose extents intersect with the bbox parameter optional preferred; orders results by proximity to the bbox extent; default
within string uses a PostGIS ST_Within operation to retrieve warped maps that fall entirely within the extent of the bbox parameter optional

Notes: Enter optional text for the query, based on the search field chosen. The query text is case insensitive. This is a simple exact string text search. For example, a search for "city New York" returns no results, but a search for "city of New York" returns 22. bbox format is y.min(lon min),x.min(lat min),y.max(lon max), x.max(lat max)

Example json format

curl -H 'Content-Type: application/json' -H 'Accept: application/json' -X GET 'http://mapwarper.net/api/v1/maps?field=title&query=Tartu&sort_key=updated_at&sort_order=desc&show_warped=1'

http://mapwarper.net/api/v1/maps?field=title&query=Tartu&sort_key=updated_at&sort_order=desc&show_warped=1

Example searching within a bounding box

http://mapwarper.net/api/v1/maps?field=title&query=Tartu&sort_key=updated_at&sort_order=desc&show_warped=1

Response

JSON API Format

{
	"data": [{
		"id": "260",
		"type": "maps",
		"attributes": {
			"title": "File:Tartu turismiskeem.png",
			"description": "From: http://commons.wikimedia.beta.wmflabs.org/wiki/File:Tartu_turismiskeem.png ",
			"width": 800,
			"height": 595,
			"status": "warped",
			"mask_status": "unmasked",
			"created_at": "2016-02-07T17:52:19.479Z",
			"updated_at": "2016-04-10T17:00:36.586Z",
			"bbox": "26.66587052714201,58.33686848133336,26.806590271771057,58.407077366797424",
			"map_type": "is_map",
			"source_uri": "http://commons.wikimedia.beta.wmflabs.org/wiki/File:Tartu_turismiskeem.png",
			"unique_id": "Tartu_turismiskeem.png",
			"date_depicted": ""
		},
		"relationships": {
			"layers": {
				"data": [{
					"id": "43",
					"type": "layers"
				}, {
					"id": "44",
					"type": "layers"
				}]
			},
			"added_by": {
				"data": {
					"id": "2",
					"type": "users"
				}
			}
		},
		"links": {
			"self": "http://mapwarper.net/api/v1/maps/260",
			"gcps_csv": "http://mapwarper.net/maps/260/gcps.csv",
			"mask": "http://mapwarper.net/mapimages/260.gml.ol",
			"geotiff": "http://mapwarper.net/maps/260/export.tif",
			"png": "http://mapwarper.net/maps/260/export.png",
			"aux_xml": "http://mapwarper.net/maps/260/export.aux_xml",
			"kml": "http://mapwarper.net/maps/260.kml",
			"tiles": "http://mapwarper.net/maps/tile/260/{z}/{x}/{y}.png",
			"wms": "http://mapwarper.net/maps/wms/260?request=GetCapabilities\u0026service=WMS\u0026version=1.1.1",
      "thumb": "/uploads/40/thumb/Screenshot_2017-03-31_15-30-47.png"
		}
	}],
	"included": [{
		"id": "43",
		"type": "layers",
		"attributes": {
			"name": "Category:Maps Of Tartu",
			"description": null
		},
		"links": {
			"self": "http://mapwarper.net/api/v1/layers/43"
		}
	}, {
		"id": "44",
		"type": "layers",
		"attributes": {
			"name": "Category:Tartu Maps",
			"description": null
		},
		"links": {
			"self": "http://mapwarper.net/api/v1/layers/44"
		}
	}],
	"links": {
      "self":"http://mapwarper.net/api/v1/maps?format=json\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=2\u0026per_page=2",
      "next":"http://mapwarper.net/api/v1/maps?format=json\u0026page%5Bnumber%5D=2\u0026page%5Bsize%5D=2\u0026per_page=2",
      "last":"http://mapwarper.net/api/v1/maps?format=json\u0026page%5Bnumber%5D=3\u0026page%5Bsize%5D=2\u0026per_page=2"
  },
	"meta": {
		"total_entries": 5,
		"total_pages": 2
	}
}

Response Elements

Data

An array of maps, each having an attributes object and, id and type and links

Name Value Description Notes
id The id for the map
type maps the type of resource
links links to the resource, and export links
attributes Attributes of the map see separate table for more detail
relationships layers, added_by the layers that the map belongs to and the user that uploaded it (see included)
included Details about the layers

Links

The top level links holds pagination links

"links": {
    "self":"http://mapwarper.net/api/v1/maps?format=json\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=2\u0026per_page=2",
    "next":"http://mapwarper.net/api/v1/maps?format=json\u0026page%5Bnumber%5D=2\u0026page%5Bsize%5D=2\u0026per_page=2",
    "last":"http://mapwarper.net/api/v1/maps?format=json\u0026page%5Bnumber%5D=3\u0026page%5Bsize%5D=2\u0026per_page=2"
},
Value Description
self the link to the current page
next the next page in the sequence
last the last page in the sequence of pages

Meta

Useful in pagination. Will show the total number of results, for example if the request is limited to returning 25 maps:

"meta": {
  "total_entries": 50,
  "total_pages": 2
}

indicates that 50 results have been found over 2 pages.

Value Description
total_entries the total number of maps found for this request
total_pages the total number of pages found

Map Links

Value Description
gcps_csv CSV for the control points
mask the GML clipping mask
geotiff The export GeoTiff url
png The export PNG url
aux_xml The export PNG XML url
kml The export KML url
tiles The Tiles template
wms The WMS getCapabilities endpoint
thumb The path to the thumbnail image

Attributes

Name Type Value Description Notes
status string the status of the map
unloaded the map has not been loaded
loading the master image is being requested from the NYPL repository
available the map has been copied and is ready to be warped
warping the map is undergoing the warping process
warped the map has been warped
published this status is set when the map should no longer be edited
map_type string indicates whether the image is of a map or another type of content
index indicates a map index or overview map
is_map indicates a map default
not_map indicates non-map content, such as a plate depicting sea monsters
updated_at datetime when the map was last updated
created_at datetime when the map was first created
title string the title of the map
description string the description of the map
height integer the height of an unwarped map
width integer the width of an unwarped map
mask_status string the status of the mask
unmasked the map has not been masked
masking the map is undergoing the masking process
masked the map has been masked
source_uri string the URI to the source map page e.g. the wiki page
unique_id string the image filename taken from the source image
date_depicted string string representation of the date that the map depicts
bbox comma-separated string of lat & lon coords a rectangle delineating the geographic area to which the search should be limited

Example geojson format

curl -H 'Content-Type: application/json' -H 'Accept: application/json' -X GET 'http://mapwarper.net/api/v1/maps?field=title&query=Tartu&sort_key=updated_at&sort_order=desc&show_warped=1&format=geojson'

http://mapwarper.net/api/v1/maps.geojson?field=title&query=Tartu&sort_key=updated_at&sort_order=desc&show_warped=1

Response

[{
	"id": 260,
	"type": "Feature",
	"properties": {
		"title": "File:Tartu turismiskeem.png",
		"description": "From: http://commons.wikimedia.beta.wmflabs.org/wiki/File:Tartu_turismiskeem.png ",
		"width": 800,
		"height": 595,
		"status": "warped",
		"created_at": "2016-02-07T17:52:19.479Z",
		"bbox": "26.66587052714201,58.33686848133336,26.806590271771057,58.407077366797424",
  	"thumb_url": "/uploads/37/thumb/map-8.png"
	},
	"geometry": {
		"type": "Polygon",
		"coordinates": "[[[26.66587052714201, 58.33686848133336], [26.806590271771057, 58.33686848133336], [26.806590271771057, 58.407077366797424], [26.66587052714201, 58.407077366797424], [26.66587052714201, 58.33686848133336]]]"
	}
}]

Get a Map

Method Definition
GET /api/v1/maps/{:id}.{:format} or
/api/v1/maps/{:id}?format={:format}

Returns a map by ID. No authentication required.

Parameters

Name Type Description Required Notes
id integer the unique identifier for a map required
format string specifies output format optional default JSON
json / geojson use to specify JSON output formart optional

Response

JSON-API

The response will be be in the following format.

{
	"data": {
		"id": "2",
		"type": "maps",
		"attributes": {
			"title": "File:Lawrence-h-slaughter-collection-of-english-maps-england.jpeg",
			"description": "From: http://commons.wikimedia.beta.wmflabs.org/wiki/File:Lawrence-h-slaughter-collection-of-english-maps-england.jpeg",
			"width": 595,
			"height": 760,
			"status": "warped",
			"mask_status": "unmasked",
			"created_at": "2015-10-20T17:17:58.300Z",
			"updated_at": "2016-06-08T10:55:13.660Z",
			"bbox": "-7.706061311682345,49.02738371829112,3.420945210059412,56.46163780182066",
			"map_type": "is_map",
			"source_uri": "http://commons.wikimedia.beta.wmflabs.org/wiki/File:Lawrence-h-slaughter-collection-of-english-maps-england.jpeg",
			"unique_id": "Lawrence-h-slaughter-collection-of-english-maps-england.jpeg",
			"date_depicted": ""
		},
		"relationships": {
			"layers": {
				"data": [{
					"id": "1",
					"type": "layers"
				}]
			},
			"added_by": {
				"data": {
					"id": "5",
					"type": "users"
				}
			}
		},
		"links": {
			"self": "http://mapwarper.net/api/v1/maps/2",
			"gcps_csv": "http://mapwarper.net/maps/2/gcps.csv",
			"mask": "http://mapwarper.net/mapimages/2.gml.ol",
			"geotiff": "http://mapwarper.net/maps/2/export.tif",
			"png": "http://mapwarper.net/maps/2/export.png",
			"aux_xml": "http://mapwarper.net/maps/2/export.aux_xml",
			"kml": "http://mapwarper.net/maps/2.kml",
			"tiles": "http://mapwarper.net/maps/tile/2/{z}/{x}/{y}.png",
			"wms": "http://mapwarper.net/maps/wms/2?request=GetCapabilities\u0026service=WMS\u0026version=1.1.1",
      "thumb": "/uploads/2/thumb/Screenshot_2017-03-31_15-30-47.png"
		}
	},
	"included": [{
		"id": "1",
		"type": "layers",
		"attributes": {
			"name": "Category:1681 maps",
			"description": null
		},
		"links": {
			"self": "http://mapwarper.net/api/v1/layers/1"
		}
	}]
}

GeoJSON Format

{
	"id": 2,
	"type": "Feature",
	"properties": {
		"title": "File:Lawrence-h-slaughter-collection-of-english-maps-england.jpeg",
		"description": "From: http://commons.wikimedia.beta.wmflabs.org/wiki/File:Lawrence-h-slaughter-collection-of-english-maps-england.jpeg",
		"width": 595,
		"height": 760,
		"status": "warped",
		"created_at": "2015-10-20T17:17:58.300Z",
		"bbox": "-7.706061311682345,49.02738371829112,3.420945210059412,56.46163780182066",
		"thumb_url": "/uploads/2/thumb/filename.png"
	},
	"geometry": {
		"type": "Polygon",
		"coordinates": "[[[-7.706061311682345, 49.02738371829112], [3.420945210059412, 49.02738371829112], [3.420945210059412, 56.46163780182066], [-7.706061311682345, 56.46163780182066], [-7.706061311682345, 49.02738371829112]]]"
	}
}

Response Elements

Data

Name Value Description Notes
id The id for the map
type maps the type of resource
links links to the resource, and export links
attributes Attributes of the map see separate table for more detail
relationships layers, added_by the layers that the map belongs to and the user that uploaded it (see included)
included Details about the layers

Map Links

Value Description
gcps_csv CSV for the control points
mask the GML clipping mask
geotiff The export GeoTiff url
png The export PNG url
aux_xml The export PNG XML url
kml The export KML url
tiles The Tiles template
wms The WMS getCapabilities endpoint
thumb The path to the thumbnail for the map

Attributes

Name Type Value Description Notes
status string the status of the map
unloaded the map has not been loaded
loading the master image is being requested from the NYPL repository
available the map has been copied and is ready to be warped
warping the map is undergoing the warping process
warped the map has been warped
published this status is set when the map should no longer be edited
map_type string indicates whether the image is of a map or another type of content
index indicates a map index or overview map
is_map indicates a map default
not_map indicates non-map content, such as a plate depicting sea monsters
updated_at datetime when the map was last updated
created_at datetime when the map was first created
title string the title of the map
description string the description of the map
height integer the height of an unwarped map
width integer the width of an unwarped map
mask_status string the status of the mask
unmasked the map has not been masked
masking the map is undergoing the masking process
masked the map has been masked
source_uri string the URI to the source map page e.g. the wiki page
unique_id string the image filename taken from the source image
date_depicted string string representation of the date that the map depicts
bbox comma-separated string of lat & lon coords a rectangle delineating the geographic area to which the search should be limited

Not Found Error

If the map is not found, the request will return the following response.

Status Response
404 (not found) {"errors":[{"title":"Not found","detail":"Couldn't find Map with 'id'=2222"}]}

Get a Map's Status

Method Definition
GET /api/v1/maps/{:id}/status

Returns a map's status. This request is used to poll a maps status while it is being transfered from the wiki image server to the map server.

Parameters

Name Type Description Required
id integer the unique identifier for the map required

Request Example

http://mapwarper.net/api/v1/maps/8991/status

Response

This request returns text. If a map has no status (i.e., has not been transferred yet), this request will return the status "loading." While the request usually takes a few seconds, it could take several.

Response Elements

Name Type Value Description Notes
status string the status of the map
unloaded the map has not been loaded
loading the master image is being requested from the NYPL repository
available the map has been copied, and is ready to be warped
warping the map is undergoing the warping process
warped the map has been warped
published this status is set when the map should no longer be edited

Layers

A layer is a mosaic in which the component maps are stitched together and displayed as one seamless map. Layers are often comprised of contiguous maps from the facing pages of a scanned book. For examples of layers, see the Plan of the town of Paramaribo, capital of Surinam or the map of New York City and Vicinity at http://maps.nypl.org/warper/layers/1404. No authentication required.

** Note: in the mapwarper application Layers are often called "Mosaics"

Query or List Layers

Method Definition
GET /api/v1/layers

Parameters

Name values Type Description Required Notes
query string search query optional
field string specified field to be searched optional default is title
name string the title of the layer optional default
description string the description of the layer optional
sort_key the field that should be used to sort the results optional default is updated_at
name string the name of the layer optional
updated_at string when the layer was last updated optional default
created_at string when the layer was created optional
percent string the percent of maps which are rectified in the layer optional ordered by integer (see below)
sort_order string the order in which the results should appear optional default is desc
asc ascending order optional
desc descending order optional default
format string specifies output format optional can also be passed in as extension, eg. maps.json
json string JSON format for layer optional default
geojson string GeoJSON format for layer optional simple array, not featurecollection
page integer the page number; use to get the next or previous page of search results optional
per_page integer number of results per page optional default is 50
bbox a comma-separated string of latitude and longitude coordinates a rectangle delineating the geographic area to which the search should be limited optional
operation string specifies how to apply the bounding box optional default is intersect
intersect string uses the PostGIS ST_Intersects operation to retrieve warped maps whose extents intersect with the bbox parameter optional preferred; orders results by proximity to the bbox extent; default
within string uses a PostGIS ST_Within operation to retrieve warped maps that fall entirely within the extent of the bbox parameter optional

Notes: Enter optional text for the query, based on the search field chosen. The query text is case insensitive. This is a simple exact string text search. For example, a search for "city New York" returns no results, but a search for "city of New York" returns 22. bbox format is y.min(lon min),x.min(lat min),y.max(lon max), x.max(lat max)

Request Example

http://mapwarper.net/api/v1/layers?query=tartu

Response

{
	"data": [
		{
			"id": "3",
			"type": "layers",
			"attributes": {
				"name": "Category:Tartu Maps",
				"description": null,
				"created_at": "2016-02-09T13:34:15.355Z",
				"updated_at": "2016-04-04T16:20:52.442Z",
				"bbox": "26.111586,58.232919,27.358788,58.486400",
				"maps_count": 1,
				"rectified_maps_count": 1,
				"is_visible": true,
				"source_uri": "https://commons.wikimedia.org/wiki/Category:Tartu Maps",
				"rectified_percent": 100
			},
			"relationships": {
				"maps": {
					"data": [
						{
							"id": "6",
							"type": "maps"
						}
					]
				}
			},
			"links": {
				"self": "http://mapwarper.net/api/v1/layers/3",
				"kml": "http://mapwarper.net/layers/3.kml",
				"tiles": "http://mapwarper.net/layers/tile/#/{z}/{x}/{y}.png",
				"wms": "http://mapwarper.net/layers/wms/3?request=GetCapabilities&service=WMS&version=1.1.1"
			}
		}],
"links": {
		"self": "http://mapwarper.net/api/v1/layers?page%5Bnumber%5D=1&page%5Bsize%5D=1&per_page=1&query=tartu",
		"next": "http://mapwarper.net/api/v1/layers?page%5Bnumber%5D=2&page%5Bsize%5D=1&per_page=1&query=tartu",
		"last": "http://mapwarper.net/api/v1/layers?page%5Bnumber%5D=2&page%5Bsize%5D=1&per_page=1&query=tartu"
	},
	"meta": {
		"total_entries": 2,
		"total_pages": 2
	}

Response Elements

Data

An array of matching layers, each having an attributes object and, id and type and links

Name Value Description Notes
id The id for the layer
type layers the type of resource
links links to the resource, and export links
attributes Attributes of the layer see separate table for more detail
relationships maps the maps that the layer has (see getting a layers maps)

Links

The top level links holds pagination links. Shown if there are more results than are contained in the response.

"links": {
    "self":"http://mapwarper.net/api/v1/layers?format=json\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=2\u0026per_page=2",
    "next":"http://mapwarper.net/api/v1/layers?format=json\u0026page%5Bnumber%5D=2\u0026page%5Bsize%5D=2\u0026per_page=2",
    "last":"http://mapwarper.net/api/v1/layers?format=json\u0026page%5Bnumber%5D=3\u0026page%5Bsize%5D=2\u0026per_page=2"
},
Value Description
self the link to the current page
next the next page in the sequence
last the last page in the sequence of pages

Meta

Useful in pagination. Will show the total number of results, for example if the request is limited to returning 25 maps, Shown if there are more results than are contained in the response.

"meta": {
  "total_entries": 50,
  "total_pages": 2
}

indicates that 50 results have been found over 2 pages.

Value Description
total_entries the total number of layers found for this request
total_pages the total number of pages found

Layer Links

Value Description
self the API link to the resourece
kml The export KML url
tiles The Tiles template
wms The WMS getCapabilities endpoint

Attributes

Name Type Description Notes
name string the title of the layer
description string description of layer
is_visible boolean/string if false, usually indicates a meta-layer or collection of atlases these meta-layers will not have WMSs
maps_count integer how many maps a layer has, as opposed to title pages, plates, and other non-map content defines a map using the map_type => is_map variable
rectified_maps_count integer how many maps in the layer are warped
rectified_percent integer the percentage of maps that are warped
bbox a comma-separated string of latitude and longitude coordinates a rectangle delineating the geographic footprint of the layer
source_uri string the URI to the source layer page e.g. the Wiki Category that the layer/mosaic represents
created_at date, time, & time zone when the layer was created in the system
updated_at date, time, & time zone when the layer was last updated

Get Layer

Method Definition
GET /api/v1/layers/{:id} or
/api/v1/layers/{:id}.json

Returns a single layer.

Parameters

Name Type Description Required Notes
id integer the unique identifier for the layer required
format string specifies output format optional default is json
json or geosjon optional

Request Examples

http://mapwarper.net/api/v1/layers/2

Response

{
	"data": {
		"id": "2",
		"type": "layers",
		"attributes": {
			"name": "Category:Maps Of Tartu",
			"description": null,
			"created_at": "2015-11-12T10:56:25.461Z",
			"updated_at": "2016-04-04T16:20:52.354Z",
			"bbox": "26.111586,58.232919,27.358788,58.486400",
			"maps_count": 2,
			"rectified_maps_count": 1,
			"is_visible": true,
			"source_uri": "https://commons.wikimedia.org/wiki/Category:Maps Of Tartu",
			"rectified_percent": 50
		},
		"relationships": {
			"maps": {
				"data": [{
					"id": "5",
					"type": "maps"
				}, {
					"id": "6",
					"type": "maps"
				}]
			}
		},
		"links": {
			"self": "http://mapwarper.net/api/v1/layers/2",
			"kml": "http://mapwarper.net/layers/2.kml",
			"tiles": "http://mapwarper.net/layers/tile/#/{z}/{x}/{y}.png",
			"wms": "http://mapwarper.net/layers/wms/2?request=GetCapabilities&service=WMS&version=1.1.1"
		}
	}
}

Response Elements

Data

Name Value Description Notes
id The id for the layer
type layers the type of resource
links links to the resource, and export links see Links
attributes Attributes of the layer see separate table for more detail
relationships layers, added_by the maps that are in the layer

Links

Value Description
self the API link to the resourece
kml The export KML url
tiles The Tiles template
wms The WMS getCapabilities endpoint

Attributes

Name Type Description Notes
name string the title of the layer
description string description of layer
is_visible boolean/string if false, usually indicates a meta-layer or collection of atlases these meta-layers will not have WMSs
maps_count integer how many maps a layer has, as opposed to title pages, plates, and other non-map content defines a map using the map_type => is_map variable
rectified_maps_count integer how many maps in the layer are warped
rectified_percent integer the percentage of maps that are warped
bbox a comma-separated string of latitude and longitude coordinates a rectangle delineating the geographic footprint of the layer
source_uri string the URI to the source layer page e.g. the Wiki Category that the layer/mosaic represents
created_at date, time, & time zone when the layer was created in the system
updated_at date, time, & time zone when the layer was last updated

Not Found Error

If the layer is not found, the request will return the following response.

Status Response
404 (not found) {"errors":[{"title":"Not found","detail":"Couldn't find Layer with 'id'=1234"}]}

GeoJSON format

http://mapwarper.net/api/v1/layers/2.geojson

{
	"id": 2,
	"type": "Feature",
	"properties": {
		"name": "Category:Maps Of Tartu",
		"description": null,
		"created_at": "2015-11-12T10:56:25.461Z",
		"bbox": "26.111586,58.232919,27.358788,58.486400",
		"maps_count": 2,
		"rectified_maps_count": 1,
		"rectified_percent": 50.0,
		"source_uri": "https://commons.wikimedia.org/wiki/Category:Maps Of Tartu"
	},
	"geometry": {
		"type": "Polygon",
		"coordinates": "[[[26.111586, 58.232919], [27.358788, 58.232919], [27.358788, 58.4864], [26.111586, 58.4864], [26.111586, 58.232919]]]"
	}
}

Get a Map's Layers

Method Definition
GET /api/v1/maps/{:map_id}/layers or
/api/v1/layers?map_id={:map_id}

Queries and returns a list of layers that a given map belongs to.

Parameters

Name Type Description Required Notes
map_id integer the unique identifier for a map required
query string search query optional
field string specified field to be searched optional default is title
name string the title of the layer optional default
description string the description of the layer optional
sort_key the field that should be used to sort the results optional default is updated_at
name string the name of the layer optional
updated_at string when the layer was last updated optional default
created_at string when the layer was created optional
percent string the percent of maps which are rectified in the layer optional ordered by integer (see below)
sort_order string the order in which the results should appear optional default is desc
asc ascending order optional
desc descending order optional default
format string specifies output format optional can also be passed in as extension, eg. maps.json
json string JSON format for layer optional default
geojson string GeoJSON format for layer optional simple array, not featurecollection
page integer the page number; use to get the next or previous page of search results optional
per_page integer number of results per page optional default is 50
bbox a comma-separated string of latitude and longitude coordinates a rectangle delineating the geographic area to which the search should be limited optional
operation string specifies how to apply the bounding box optional default is intersect
intersect string uses the PostGIS ST_Intersects operation to retrieve warped maps whose extents intersect with the bbox parameter optional preferred; orders results by proximity to the bbox extent; default
within string uses a PostGIS ST_Within operation to retrieve warped maps that fall entirely within the extent of the bbox parameter optional

Request Example

http://mapwarper.net/api/v1/maps/3/layers?query=tartu&sort_key=percent

Alternatively, the URL can be constructed by passing in the map_id as a paramter:

http://mapwarper.net/api/v1/layers?query=tartu&sort_key=percent&map_id=3

Response

Same response format as for listing and querying layers. See Query or List Layers

Get a Layer's Maps

Method Definition
GET /api/v1/layers/{:layer_id}/maps or
/api/v1/layers?layer_id={:layer_id}

Returns a paginated list of the maps that comprise a given layer.

Parameters

Name values Type Description Required Notes
layer_id integer the unique identifier for the layer required
query string search query optional
field string specified field to be searched optional default is title
title string the title of the map optional default
description string the description of the map optional
publisher string the publisher optional
author string the author of the map optional
status string the status optional
sort_key the field that should be used to sort the results optional default is updated_at
title string the title of the map optional
updated_at string when the map was last updated optional default
created_at string when the map was created optional
status string the status of the map optional ordered by integer (see below)
sort_order string the order in which the results should appear optional default is desc
asc ascending order optional
desc descending order optional default
show_warped integer limits to maps that have already been warped optional
1 integer limits to maps that have already been warped optional
0 integer gets all maps, warped and unwarped optional default
format string specifies output format optional can also be passed in as extension, eg. maps.json
json string JSON format for maps optional default
geojson string GeoJSON format for maps optional simple array, not featurecollection
page integer the page number; use to get the next or previous page of search results optional
per_page integer number of results per page optional default is 50
bbox a comma-separated string of latitude and longitude coordinates a rectangle delineating the geographic area to which the search should be limited optional
operation string specifies how to apply the bounding box optional default is intersect
intersect string uses the PostGIS ST_Intersects operation to retrieve warped maps whose extents intersect with the bbox parameter optional preferred; orders results by proximity to the bbox extent; default
within string uses a PostGIS ST_Within operation to retrieve warped maps that fall entirely within the extent of the bbox parameter optional

Request Examples

http://mapwarper.net/api/v1/layers/3/maps or

http://mapwarper.net/api/v1/layers?layer_id=3

Response

Same response as for listing and querying layers.

See Search for Maps

Map and Layer Web Map Services

The WMS and Tile services are available and are now shown in the standard JSON responses

Create Layer

Creates a new layer and adding several existing maps to it at the same time. Authentication required.

Method Definition
POST /api/v1/layers

Parameters

The body of the request should be in JSON-API format. data may also have ```map_ids`` - an array of existing map ids to add to the layer.

Name Type Description Notes
data
type string "layers" required
map_ids array array of integers of the maps to add optional
attributes
name string the name of the layer required
description string the description of the layer optional

Example:

{
	"data": {
		"type": "layers",
		"attributes": {
			"name": "a new layer",
			"description": "new description"
		},
    "map_ids":[123,553,224]
	}
}

cURL Example

curl -H "Content-Type: application/json" -H 'Accept: application/json' -X POST -d '{"data":{"type":"layers","attributes":{"name":"a new layer","description":"new description"},"map_ids":[123,553,224]}}' http://mapwarper.net/api/v1/layers -b cookie

Response

If successful, the response should return the new layer in json api format

Update Layer

Updates a new layer and adding several existing maps to it at the same time. This could be used to add many maps at the same time to a layer. Authentication required. Only the owner of the layer or an editor is authorized.

Method Definition
PATCH /api/v1/layers/{:id}

Parameters

Name Type Description Required Notes
id integer the unique identifier for the layer required

The body of the request should be in JSON-API format. data may also have ```map_ids`` - an array of existing map ids to add to the layer.

Name Type Description Notes
data
type string "layers" required
map_ids array array of integers of the maps to add optional
attributes
name string the name of the layer optional
description string the description of the layer optional

Example:

{
	"data": {
		"type": "layers",
		"attributes": {
			"name": "a different name"
		},
    "map_ids":[4423,22]
	}
}

cURL Example

curl -H "Content-Type: application/json" -H 'Accept: application/json' -X PATCH -d '{"data":{"type":"layers","attributes":{"name":"a different name"},"map_ids":[4423,22]}}' http://mapwarper.net/api/v1/layers -b cookie

Response

If successful, the response should return the updated layer in json api format

Destroy Layer

Destroys a layer. Authentication required. Only the owner of the layer or an editor is authorized.

Method Definition
DELETE /api/v1/layers{:id}

Parameters

Name Type Description Required Notes
id integer the unique identifier for the layer required

cURL Example

curl -H "Content-Type: application/json" -H 'Accept: application/json' -X DELETE -d http://mapwarper.net/api/v1/layers/12 -b cookie

Response

If successful, the response should return the deleted layer in json api format

Remove Map From Layer

Removes a single map from a layer. Authentication required. Only the owner of the layer or an editor is authorized.

Method Definition
PATCH /api/v1/layers/{:id}/remove_map

Parameters

It takes a single parameter, map_id containing the id of the map to be removed.

Name Type Description Required Notes
id integer the unique identifier for the layer required
map_id integer unique id of the map to be removed required

cURL Example

curl -H "Content-Type: application/json" -H 'Accept: application/json' -X PATCH -d '{"map_id":123}' http://mapwarper.net/api/v1/layers/2/remove_map -b cookie

Response

If successful, the response should return the updated layer in json api format

If error, the following will be returned (with 422 status)

{
	"errors": [{
		"title": "Layer error",
		"detail": "Error removing map."
	}]
}

Ground Control Points

Ground control points are the user-selected locations used to warp an image.

List and Sort Control Points

Method Definition
GET /api/v1/gcps

Gets and sorts all control points. No authentication required.

Parameters

Name values Type Description Required Notes
sort_key the field that should be used to sort the results optional default is updated_at
map_id string the id of the map the GCP belongs to optional
lat string the latitude of the ground control point optional
lon string the longitude of the ground control point optional
x string the x coordinate on the image that corresponds to "lon" optional
y string the y coordinate on the image that corresponds to "lat" optional
updated_at string when the GCP was last updated optional default
created_at string when the GCP was first created optional
sort_order string the order in which the results should appear optional default is desc
asc ascending order optional
desc descending order optional default
page integer the page number; use to get the next or previous page of search results optional
per_page integer number of results per page optional default is 50
map_id integer restricts results to the map given optional

Request Examples

http://mapwarper.net/api/v1/gcps?per_page=2&sort_key=updated_at

Response

{
	"data": [
		{
			"id": "2",
			"type": "gcps",
			"attributes": {
				"map_id": 2,
				"x": 151.833333333328,
				"y": 392.666666666666,
				"lat": "52.7603488553",
				"lon": "-4.6579885155",
				"created_at": "2015-10-23T12:38:29.023Z",
				"updated_at": "2016-06-08T10:54:44.094Z",
				"error": null
			}
		},
		{
			"id": "3",
			"type": "gcps",
			"attributes": {
				"map_id": 2,
				"x": 72.2142857142853,
				"y": 712.952380952381,
				"lat": "49.8494421783",
				"lon": "-5.2512502342",
				"created_at": "2015-10-23T12:38:36.048Z",
				"updated_at": "2016-06-08T10:54:34.903Z",
				"error": null
			}
		}
	],
	"links": {
		"self": "http://mapwarper.net/api/v1/gcps?page%5Bnumber%5D=1&page%5Bsize%5D=2&per_page=2&sort_key=updated_at",
		"next": "http://mapwarper.net/api/v1/gcps?page%5Bnumber%5D=2&page%5Bsize%5D=2&per_page=2&sort_key=updated_at",
		"last": "http://mapwarper.net/api/v1/gcps?page%5Bnumber%5D=7&page%5Bsize%5D=2&per_page=2&sort_key=updated_at"
	},
	"meta": {
		"total_entries": 13,
		"total_pages": 7
	}
}

Response Elements

Data

An array of control points, each having an attributes object and, id and type and links

Name Value Description Notes
id The id for the gcp
type gcps the type of resource
links links to the resource, and export links
attributes Attributes of the gcps see separate table for more detail

Links

The top level links holds pagination links. Shown if there are more results than are contained in the response.

"links": {
		"self": "http://mapwarper.net/api/v1/gcps?page%5Bnumber%5D=1&page%5Bsize%5D=2&per_page=2&sort_key=updated_at",
		"next": "http://mapwarper.net/api/v1/gcps?page%5Bnumber%5D=2&page%5Bsize%5D=2&per_page=2&sort_key=updated_at",
		"last": "http://mapwarper.net/api/v1/gcps?page%5Bnumber%5D=7&page%5Bsize%5D=2&per_page=2&sort_key=updated_at"
},
Value Description
self the link to the current page
next the next page in the sequence
last the last page in the sequence of pages

Meta

Useful in pagination. Will show the total number of results, for example if the request is limited to returning 25 maps, Shown if there are more results than are contained in the response.

"meta": {
  "total_entries": 50,
  "total_pages": 2
}

indicates that 50 results have been found over 2 pages.

Value Description
total_entries the total number of layers found for this request
total_pages the total number of pages found

Attributes

Name Type Description Notes
map_id id the unique identifier for the map the point belongs to see below for other way to get gcps for a map
lat big decimal the latitude of the ground control point
lon big decimal the longitude of the ground control point
x float the x coordinate on the image that corresponds to "lon"
y float the y coordinate on the image that corresponds to "lat"
error float the calculated root mean square error, or distortion, for the ground control point null unless called via /api/v1/maps/{:map_id}/gcps see below
created_at date, time, & time zone the date and time when the ground control point was created
updated_at date, time, & time zone the date and time when the ground control point was last updated

Get a Map's Ground Control Points

There are two different ways to get the control points of a map:

Method Definition
GET /api/v1/maps/{:map_id}/gcps or
/api/v1/gcps?map_id={:map_id} (see above)

Returns a list of the ground control points used to warp a map, as well as their calculated errors. No authentication required.

** Note: api/v1/maps/:id/gcps includes the calculated error but with no sorting or pagination, whereas api/v1/gcps?map_id={:map_id} whilst has sorting and pagination but with no calculated error.

Parameters

Name Type Description Required Notes
map_id integer the unique identifier for the map required

Request Examples

http://mapwarper.net/api/v1/maps/2/gcps

Response

The response will be a list of ground control points in the following format.

{
	"data": [
		{
			"id": "1",
			"type": "gcps",
			"attributes": {
				"map_id": 2,
				"x": 479.35714285714,
				"y": 380,
				"lat": "52.959343811",
				"lon": "0.593476328",
				"created_at": "2015-10-23T12:38:24.222Z",
				"updated_at": "2015-10-23T12:38:24.222Z",
				"error": 13.781432496303088
			}
		},
		...snip...
		{
			"id": "19",
			"type": "gcps",
			"attributes": {
				"map_id": 2,
				"x": 110.21428571429,
				"y": 119.42857142857,
				"lat": "54.9945666448",
				"lon": "-5.1378768477",
				"created_at": "2016-06-08T10:54:28.391Z",
				"updated_at": "2016-06-08T10:54:28.391Z",
				"error": 15.401820748382049
			}
		}
	],
	"meta": {
		"map-error": 17.280250155403902
	}
}

Response Elements

Data

An array of control points, each having an attributes object and, id and type and links

Name Value Description Notes
id The id for the gcp
type gcps the type of resource
attributes Attributes of the gcps see separate table for more detail

Meta

Contains details about the combined error for the control points for the entire map

	"meta": {
		"map-error": 17.280250155403902
	}

Attributes

Name Type Description Notes
map_id id the unique identifier for the map the point belongs to
lat big decimal the latitude of the ground control point
lon big decimal the longitude of the ground control point
x float the x coordinate on the image that corresponds to "lon"
y float the y coordinate on the image that corresponds to "lat"
error float the calculated root mean square error, or distortion, for the ground control point
created_at date, time, & time zone the date and time when the ground control point was created
updated_at date, time, & time zone the date and time when the ground control point was last updated

Get a Single Ground Control Point

Method Definition
GET /api/v1/gcps/{:gcp_id}

Returns a specified ground control point by ID. No authentication required.

Parameters

Name Type Description Required Notes
gcp_id integer the unique identifier for the ground control point required

Example

http://mapwarper.net/api/v1/gcps/2

Response

{
	"data": {
		"id": "2",
		"type": "gcps",
		"attributes": {
			"map_id": 2,
			"x": 151.833333333328,
			"y": 392.666666666666,
			"lat": "52.7603488553",
			"lon": "-4.6579885155",
			"created_at": "2015-10-23T12:38:29.023Z",
			"updated_at": "2016-06-08T10:54:44.094Z",
			"error": null
		}
	}
}

Response Elements

Data

Name Value Description Notes
id The id for the gcp
type gcps the type of resource
attributes Attributes of the gcps see separate table for more detail

Attributes

Name Type Description Notes
map_id id the unique identifier for the map the point belongs to
lat big decimal the latitude of the ground control point
lon big decimal the longitude of the ground control point
x float the x coordinate on the image that corresponds to "lon"
y float the y coordinate on the image that corresponds to "lat"
error float the calculated root mean square error, or distortion, for the ground control point
created_at date, time, & time zone the date and time when the ground control point was created
updated_at date, time, & time zone the date and time when the ground control point was last updated

If the GCP is not found, the request will return the following response:

Status Response
404 (not found) {"errors":[{"title":"Not found","detail":"Couldn't find Gcp with 'id'=2222"}]}

Add Ground Control Point

Method Definition
POST /api/v1/gcps

Adds the ground control points on which a warp will be based, passing in JSON-API for the GCP. Requires authentication.

Parameters

The body of the request should be in JSON-API format with the following attributes:

Name Type Description Notes
lat big decimal the latitude of the ground control point required
lon big decimal the longitude of the ground control point required
x float the x coordinate on the image that corresponds to "lon" required
y float the y coordinate on the image that corresponds to "lat" required

Example:

{
	"data": {
		"type": "gcps",
		"attributes": {
			"map_id": 2,
			"x": 2,
			"y":3,
			"lat": "52.56",
			"lon": "-4.65"
		}
	}
}

cURL Example

curl -H "Content-Type: application/json" -H 'Accept: application/json' -X POST -d '{"data":{"type":"gcps","attributes":{"x":1,"y":2,"lat":33.3,"lon":44.4,"map_id":2}}}' http://mapwarper.net/api/v1/gcps -b cookie

Response

If successful, the response should return the created point:

{
	"data": {
		"id": "21",
		"type": "gcps",
		"attributes": {
			"map_id": 2,
			"x": 1.0,
			"y": 2.0,
			"lat": "33.3",
			"lon": "44.4",
			"created_at": "2016-06-10T13:50:34.193Z",
			"updated_at": "2016-06-10T13:50:34.193Z",
			"error": null
		}
	}
}

An error will return something similar to the following message.

{
	"errors": [{
		"source": {
			"pointer": "/data/attributes/x"
		},
		"detail": "is not a number"
	}, {
		"source": {
			"pointer": "/data/attributes/x"
		},
		"detail": "can't be blank"
	}]
}

Update a GCP

Method Definition
PATCH /api/v1/gcps/{:gcp_id}

Updates a given GCP. Requires authentication.

Attributes

Name Type Description Required Notes
map_id integer the unique identifier of the map the point belongs to optional
lat big decimal the latitude of the ground control point to warp to optional
lon big decimal the longitude of the ground control point to warp to optional
x float the x coordinate on the unwarped image that corresponds to "lon" optional
y float the y coordinate on the unwarped image that corresponds to "lat" optional

Example using cURL and cookie authentication

In this example, we are changing the value of x and y.

curl -H "Content-Type: application/json" -H 'Accept: application/json' -X PUT -d '{"data":{"type":"gcps","attributes":{"x":22,"y":55,"map_id":2}}}' http://mapwarper.net/api/v1/gcps/21 -b cookie

Response

If successful the response will be the updated control point.

Example:

{
	"data": {
		"id": "21",
		"type": "gcps",
		"attributes": {
			"map_id": 2,
			"x": 22.0,
			"y": 55.0,
			"lat": "33.3",
			"lon": "44.4",
			"created_at": "2016-06-10T13:50:34.193Z",
			"updated_at": "2016-06-10T14:59:56.596Z",
			"error": null
		}
	}
}

Delete a GCP

Method Definition
DELETE /api/v1/gcp/{:gcp_id}

Deletes a ground control point. Requires authentication.

Parameters

Name Type Description Required
gcp_id integer the unique identifier for the ground control point required

Example:

curl example

curl -H "Content-Type: application/json" -H 'Accept: application/json' -X DELETE http://mapwarper.net/api/v1/gcps/21 -b cookie

Response

If deleted, it will return with the deleted point.

If the GCP is not found, the request will return the following response:

Status Response
404 (not found) {"errors":[{"title":"Not found","detail":"Couldn't find Gcp with 'id'=2222"}]}

Add Many GCPs

Adds many Ground Control Point at once to one or more maps Authentication required. Editor role authorized only.

Method Definition
POST /api/v1/gcps/add_many

Parameters

Name Type Description Required
gcps array an array of control points required

Each gcp should have a mapid attribute to be able to add the control point to the correct map. Points cannot be added twice.

{
	"gcps": [{
		"mapid": 123,
		"x": 2,
		"y": 3,
		"lat": "52.56",
		"lon": "-4.65"
	}, {
		"mapid": 123,
		"x": 12,
		"y": 23,
		"lat": "32.56",
		"lon": "-2.65"
	}]
}

cURL Example

curl -H "Content-Type: application/json" -H 'Accept: application/json' -X POST -d '{"gcps":[{"mapid":123,"x":2,"y":3,"lat":"52.56","lon":"-4.65"},{"mapid":123,"x":12,"y":23,"lat":"32.56","lon":"-2.65"}]}' http://mapwarper.net/api/v1/gcps/add_many -b cookie

Response

If successful, the response should return the newly added gcps

{
  "data": [
    {
      "id": "228",
      "type": "gcps",
      "attributes": {
        "map_id": 123,
        "x": 2.0,
        "y": 3.0,
        "lat": "52.56",
        "lon": "-4.65",
        "created_at": "2016-06-11T16:29:32.948Z",
        "updated_at": "2016-06-11T16:29:32.948Z",
        "error": null
      }
    },
    {
      "id": "228",
      "type": "gcps",
      "attributes": {
        "map_id": 542,
        "x": 2.0,
        "y": 3.0,
        "lat": "52.56",
        "lon": "-4.65",
        "created_at": "2016-06-11T16:29:32.948Z",
        "updated_at": "2016-06-11T16:29:32.948Z",
        "error": null
      }
    }
  ]
}

Errors

If a map cannot be found

{"errors":[{"title":"Not found","detail":"Couldn't find Map with 'id'=123"}]}

Masking

Uses GML to mask a portion of the map. This essentially crops the map. Masking is used to delete the borders around the map images to make a seamless layer of contiguous maps.

Get Mask

Method Definition
GET http://mapwarper.net/mapimages/{:map_id}.gml.ol

Gets a GML string containing coordinates for the polygon(s) to mask over. No authentication required.

** Note: The correct way to find the path to the mask is to get the Map object and look in it's links

"mask": "http://mapwarper.net/mapimages/260.gml.ol",

Examples

http://mapwarper.net/shared/masks/7449.gml.ol

Response Example

{{{
<wfs:FeatureCollection xmlns:wfs="http://www.opengis.net/wfs"><gml:featureMember xmlns:gml="http://www.opengis.net/gml"><feature:features xmlns:feature="http://mapserver.gis.umn.edu/mapserver" fid="OpenLayers.Feature.Vector_207"><feature:geometry><gml:Polygon><gml:outerBoundaryIs><gml:LinearRing><gml:coordinates decimal="." cs="," ts=" ">1474.9689999999998,5425.602 3365.091,5357.612 3582.659,5126.446 3555.463,4813.692 3637.051,4487.34 4276.157,3753.048 4575.313,3113.942 4493.725,1917.318 4072.187,1645.358 3079.533,1441.388 2467.623,1427.79 2304.447,1264.614 1529.3609999999999,1332.6039999999998 1542.9589999999998,1862.926 2005.291,2202.876 1624.547,2542.826 </nowiki><nowiki>1651.743,3195.53 1665.341,3698.656 1692.5369999999998,3997.812 2005.291,4201.782 2005.291,4419.35 1570.155,5140.044 1474.9689999999998,5425.602</gml:coordinates></gml:LinearRing></gml:outerBoundaryIs></gml:Polygon></feature:geometry></feature:features></gml:featureMember><gml:featureMember xmlns:gml="http://www.opengis.net/gml"><feature:features xmlns:feature="http://mapserver.gis.umn.edu/mapserver" fid="OpenLayers.Feature.Vector_201"><feature:geometry><gml:Polygon><gml:outerBoundaryIs><gml:LinearRing><gml:coordinates decimal="." cs="," ts=" ">1447.773,4854.486 1828.5169999999998,4582.526 1950.899,4242.576 1774.125,4065.802 1583.753,3902.626 1610.949,3345.108 1597.3509999999999,2923.57 1447.773,2638.0119999999997 1379.783,2787.59 1338.989,4854.486 1447.773,4854.486</gml:coordinates></gml:LinearRing></gml:outerBoundaryIs></gml:Polygon></feature:geometry></feature:features></gml:featureMember></wfs:FeatureCollection>
}}}

Save Mask

Method Definition
POST /api/v1/maps/:id/mask

Saves a mask. Returns map json. Requires authentication.

Parameters

Name Type Description Required Notes
map_id integer the unique indentifer for the map required
output gml the GML required

cURL Example

{{{
curl -X POST -d "format=json" -d 'output=<wfs:FeatureCollection xmlns:wfs="http://www.opengis.net/wfs"><gml:featureMember xmlns:gml="http://www.opengis.net/gml"><feature:features xmlns:feature="http://mapserver.gis.umn.edu/mapserver" fid="OpenLayers.Feature.Vector_207"><feature:geometry><gml:Polygon><gml:outerBoundaryIs><gml:LinearRing><gml:coordinates decimal="." cs="," ts=" ">1490.0376070686068,5380.396178794179 3342.4880893970894,5380.214910602912 3582.659,5126.446 3555.463,4813.692 3637.051,4487.34 4276.157,3753.048 4575.313,3113.942 4546.465124740124,1412.519663201663 2417.4615530145525,1317.354124740125 1431.415054054054,1294.9324823284824 1447.7525384615387,2187.807392931393 1434.5375363825372,5034.563750519751 1490.0376070686068,5380.396178794179</gml:coordinates></gml:LinearRing></gml:outerBoundaryIs></gml:Polygon></feature:geometry></feature:features></gml:featureMember></wfs:FeatureCollection>' http://mapwarper.net/api/v1/maps/2/mask -b cookie
}}}

Response

A successful call will return the applicable map in json-api format.

Delete Mask

Method Definition
DELETE /api/v1/maps/{:map_id}/mask

Deletes a mask. Requires authentication.

Parameters

Name Type Description Required
map_id integer the unique identifier for the map required

Response

If sucessfully deleted the response will be the affected map in json api format

###Crop / Mask Map

Method Definition
PATCH /api/v1/maps/{:map_id}/crop

Applies the clipping mask to a map, but does not warp it. A clipping mask should be saved before calling this. Requires authentication.

Example

curl -H "Content-Type: application/json" -H 'Accept: application/json' -X PATCH http://mapwarper.net/api/v1/maps/2/crop -b cookie

Response

If successul, returns the target map in json

Errors

If there is no mask saved, the following error will be returned (Error Status 422)

{
	"errors": [{
		"title": "Mask error",
		"detail": "Mask file not found"
	}]
}

Save, Mask, and Warp Map

Method Definition
PATCH /api/v1/maps/:map_id/mask_crop_rectify

Rolls the calls into one. Saves the mask, applies the mask to the map, and warps the map using the mask. Requires authentication.

Parameters

Name Type Description Required
map_id integer the unique identifier for the map required
output gml the GML

Example

{{{
curl -X POST -d "format=json" -d 'output=<wfs:FeatureCollection xmlns:wfs="http://www.opengis.net/wfs"><gml:featureMember xmlns:gml="http://www.opengis.net/gml"><feature:features xmlns:feature="http://mapserver.gis.umn.edu/mapserver" fid="OpenLayers.Feature.Vector_207"><feature:geometry><gml:Polygon><gml:outerBoundaryIs><gml:LinearRing><gml:coordinates decimal="." cs="," ts=" ">1490.0376070686068,5380.396178794179 3342.4880893970894,5380.214910602912 3582.659,5126.446 3555.463,4813.692 3637.051,4487.34 4276.157,3753.048 4575.313,3113.942 4546.465124740124,1412.519663201663 2417.4615530145525,1317.354124740125 1431.415054054054,1294.9324823284824 1447.7525384615387,2187.807392931393 1434.5375363825372,5034.563750519751 1490.0376070686068,5380.396178794179</gml:coordinates></gml:LinearRing></gml:outerBoundaryIs></gml:Polygon></feature:geometry></feature:features></gml:featureMember></wfs:FeatureCollection>' http://mapwarper.net/api/v1/maps/2/mask_crop_rectify -b cookie
}}}

Response

As rectify call.


Warping

Method Definition
PATCH /api/v1/maps/{:map_id}/rectify

Warps or rectifies a map according to its saved GCPs and the parameters passed in. Requires authentication.

Curl Example

curl -X PATCH -d "use_mask=false&format=json" -u email@example.com:password  http://mapwarper.net/api/v1/maps/7449/rectify

Parameters

Name Type Description Required Notes
map_id integer the unique identifier for the map required
use_mask boolean applies any saved mask to the map optional default is false
format string specifies output format optional default is HTML
json requests output in JSON format, rather than HTML or XML optional

Other Parameters

The following options specify the algorithm or method that should be used to warp a map.

Name Type Description Required Notes
resample_options string optional
near nearest neighbor optional fastest processing; default
bilinear bilinear interpolation optional
cubic cubic optional good option, but slower
cubicspline cubic spline optional slowest; best quality
transform_options string optional
auto optional default
p1 1st order polynomial optional requires a minimum of 3 GCPs
p2 2nd order polynomial optional requires a minimum of 6 GCPs
p3 3rd order polynomial optional requires a minimum of 10 GCPs
tps thin plate spline optional requires many evenly-distributed GCPs

Response

If successful the response will the target map in json format

If there is an error, a 422 status code is sent along with json

Errors

Two common error messages are:

Not enough Ground Control Points

{
	"errors": [{
		"title": "Not enough gcps",
		"detail": "Map needs at least 3 control points to rectify."
	}]
}

Map currently being rectified

{
	"errors": [{
		"title": "Map busy",
		"detail": "Map currently being rectified. Try again later."
	}]
}

Maps

Create Map

Method Definition
POST /api/v1/maps

Creates a new map. Requires authentication.

Parameters

The body of the request should be in JSON-API format with the following attribute.

Name Type Description Notes
title string the title of the map required
description string the title of the map
source_uri string the URI to the source map page e.g. the wiki page
unique_id string the image filename taken from the source image
date_depicted integer or string Date the map is depicted numeric, max 4 characters long. Used in search by date
map_type string string one of "is_map", "index", "not_map" defaults to is_map
unique_id string a unique id for the map needs to be unique
issue_year integer or string Date of issue numeric, max 4 characters long. (e.g. 1923)
tag_list string comma separated string of tags to add e.g. "new york, foo, bar"
subject_area string
call_number string
publisher string
publication_place string
authors string
scale string
metadata_projection string
metadata_lat integer or string numeric
metadata_lon integer or string numeric

Then either:

Name Type Description Notes
upload_url string URL to a remote image e.g. "http://example.com/map.jpg"

OR

Name Type Description Notes
upload string encoded string see below
upload_file_name string filename with the base64 image

Creation of base64 encoded image:

image_data = Base64.encode64(File.open("map.jpg", "rb").read) upload = "data:image/png;base64,#{image_data}" 'data' => {'type' => "maps", "attributes"=>{"description"=>"desc", "title"=>"new map", "upload" => upload, "upload_file_name" => "map.jpg"}}

Example:

A basic example, please add more metadata attributes when you are adding maps!

{
	"data": {
		"type": "maps",
		"attributes": {
      "title": "initial title",
      "upload_url": "http://example.com/map.jpg"
		}
	}
}

cURL Example

curl -H "Content-Type: application/json" -H 'Accept: application/json'  -X POST -d '{"data":{"type":"maps","attributes": {"title":"initial title"}}}' http://mapwarper.net/api/v1/maps -b cookie

Response

If successful, the response should return the created map in json format

Errors

Status 422 and message for example if the issue_year is not a number:

{
	"errors": [{
		"source": {
			"pointer": "/data/attributes/issue_year"
		},
		"detail": "is not a number"
	}]
}

Update Map

Method Definition
PATCH /api/v1/maps/{:id}

Updates a map. Allows an editor to change title and description. Requires authentication. Only the owner of the map or an editor is authorized.

Parameters

Name Type Description Required
id integer the unique identifier for the map required

The body of the request should be in JSON-API format with optional attributes

Name Type Description Notes
title string the title of the map
description string the title of the map
source_uri string the URI to the source map page e.g. the wiki page
unique_id string the image filename taken from the source image
date_depicted integer or string Date the map is depicted numeric, max 4 characters long. Used in search by date
map_type string string one of "is_map", "index", "not_map" defaults to is_map
unique_id string a unique id for the map needs to be unique
issue_year integer or string Date of issue numeric, max 4 characters long. (e.g. 1923)
tag_list string comma separated string of tags to add e.g. "new york, foo, bar"
subject_area string
call_number string
publisher string
publication_place string
authors string
scale string
metadata_projection string
metadata_lat integer or string numeric
metadata_lon integer or string numeric

Note that you cannot re-upload an image by updating it.

Example:

{
	"data": {
		"type": "maps",
		"attributes": {
      "title": "New Improved title",
      "description": "A better reading description"
		}
	}
}

cURL Example

curl -H "Content-Type: application/json" -H 'Accept: application/json' -X PATCH -d '{"data":{"type":"maps","attributes": {"title":"A New Improved Title"}}}' http://mapwarper.net/api/v1/maps/3 -b cookie

Response

If successful, the response should return the created map in json format

Errors

Status 422 and message with errors.

Destroy Map

Method Definition
DELETE /api/v1/maps/{:id}

Deletes a map. Allows an editor to delete a specific map. Requires authentication. Only the owner of the map or an editor is authorized.

Parameters

Name Type Description Required
id integer the unique identifier for the map required

cURL Example

curl -H "Content-Type: application/json" -H 'Accept: application/json' -X DELETE http://mapwarper.net/api/v1/maps/3 -b cookie

Response

If successful, the response should return the created map in json format

Errors

Status 422 and message with errors.

Get a User

Method Definition
GET /api/v1/users/{:id}

Returns a specified user by ID. Authentication required.

Parameters | Name | | Type | Description | Required | Notes | |------|---|---------|------------------------------------|----------|-------| | id | | integer | the unique identifier for the user | required | |

Example

http://mapwarper.net/api/v1/users/3

Response

A response of a user with normal user authorizion

{
	"data": {
		"id": "23",
		"type": "users",
		"attributes": {
			"login": "example",
			"created_at": "2013-08-26T15:37:34.619Z",
			"enabled": true,
			"provider": null
		},
		"links": {
			"self": "http://mapwarper.net/api/v1/users/23"
		}
	}
}

Response Elements

Data

Name Value Description Notes
id The id for the user
type users the type of resource
attributes Attributes of the user see table for more detail

Attributes

Name Type Description Notes
login string the name of the user
enabled boolean whether the user is enabled or not
provider string if the user is from github, mediawiki, twitter etc

If the user is not found, the request will return the following response:

Status Response
404 (not found) {"errors":[{"title":"Not found","detail":"Couldn't find User with 'id'=2222"}]}

Imports


Activity & Stats

Gets the activity of users actions over maps and control points, and a report on user statistics. Requires authentication. Most calls do not require special authorisation (except the user stats call).

List Activity

Lists all activity across maps and control points, ordered by created_at desc Authentication required.

Method Definition
GET /api/v1/activity

Parameters

Name Type Description Required Notes
page integer the page number; use to get the next or previous page of search results optional
per_page integer number of results per page optional default is 50

cURL Example

curl -H "Content-Type: application/json" -H 'Accept: application/json' -X GET  http://mapwarper.net/api/v1/activity?per_page=2 -b cookie

Response

{
	"data": [
		{
			"id": 2158,
			"auditable_id": 228,
			"auditable_type": "Gcp",
			"user_id": 4,
			"action": "create",
			"version": 1,
			"created_at": "2016-06-11T16:29:32.951Z"
		},
		{
			"id": 2156,
			"auditable_id": 294,
			"auditable_type": "Map",
			"user_id": 2,
			"action": "create",
			"version": 1,
			"created_at": "2016-06-10T17:20:31.175Z"
		}
	],
	"meta": {
		"total_entries": 2140,
		"total_pages": 1070
	}
}

Response Elements

Data

Name Type Description Notes
id integer unique identifier of the activity
auditable_id integer unique identifier of the item the activity refers to e.g. Gcp or Map
auditable_type string The type ofitem the activity refers to e.g. Gcp or Map
user_id integer unique identifier of the user doing the action
action string the type of action one of: "create", "update", "destroy"
version integer the version of the item e.g. a created map will always be version 1 initially
created_at datetime the time of the action

Meta

Useful in pagination. Will show the total number of results, for example if the request is limited to returning 25 maps:

"meta": {
  "total_entries": 50,
  "total_pages": 2
}

List Maps Activity

Lists all activity across just maps, ordered by created_at desc Authentication required.

Method Definition
GET /api/v1/activity/maps

Parameters

Name Type Description Required Notes
page integer the page number; use to get the next or previous page of search results optional
per_page integer number of results per page optional default is 50

cURL Example

curl -H "Content-Type: application/json" -H 'Accept: application/json' -X GET  http://mapwarper.net/api/v1/activity/maps?per_page=2 -b cookie

Response

{
	"data": [
		{
			"id": 2158,
			"auditable_id": 294,
			"auditable_type": "Map",
			"user_id": 4,
			"action": "update",
			"version": 1,
			"created_at": "2016-06-11T16:29:32.951Z"
		},
		{
			"id": 2156,
			"auditable_id": 294,
			"auditable_type": "Map",
			"user_id": 2,
			"action": "create",
			"version": 1,
			"created_at": "2016-06-10T17:20:31.175Z"
		}
	],
	"meta": {
		"total_entries": 2140,
		"total_pages": 1070
	}
}
curl -H "Content-Type: application/json" -X GET  http://mapwarper.net/api/v1/activity/maps?per_page=2 -b cookie

Response Elements

Data

Name Type Description Notes
id integer unique identifier of the activity
auditable_id integer unique identifier of the item the activity refers to e.g. Map
auditable_type string The type ofitem the activity refers to e.g. Map
user_id integer unique identifier of the user doing the action
action string the type of action one of: "create", "update", "destroy"
version integer the version of the item e.g. a created map will always be version 1 initially
created_at datetime the time of the action

Meta

Useful in pagination. Will show the total number of results, for example if the request is limited to returning 25 maps:

"meta": {
  "total_entries": 50,
  "total_pages": 2
}

List Map Activity

Lists all activity across one specified map, ordered by created_at desc Authentication required.

Method Definition
GET /api/v1/activity/maps/{:id}

Parameters

Name Type Description Required Notes
id integer unique identifier of the map required
page integer the page number; use to get the next or previous page of search results optional
per_page integer number of results per page optional default is 50

cURL Example

curl -H "Content-Type: application/json" -X GET  http://mapwarper.net/api/v1/activity/maps/260?per_page=2 -b cookie

Response

{
	"data": [
		{
			"id": 2116,
			"auditable_id": 260,
			"auditable_type": "Map",
			"user_id": 2,
			"action": "update",
			"version": 16,
			"created_at": "2016-04-10T17:00:36.588Z"
		},
		{
			"id": 2115,
			"auditable_id": 260,
			"auditable_type": "Map",
			"user_id": 2,
			"action": "update",
			"version": 15,
			"created_at": "2016-04-10T17:00:31.684Z"
		}
	],
	"meta": {
		"total_entries": 16,
		"total_pages": 8
	}
}

Response Elements

Data

Name Type Description Notes
id integer unique identifier of the activity
auditable_id integer unique identifier of the item the activity refers to
auditable_type string The type ofitem the activity refers to e.g. Map
user_id integer unique identifier of the user doing the action
action string the type of action one of: "create", "update", "destroy"
version integer the version of the item e.g. a created map will always be version 1 initially
created_at datetime the time of the action

Meta

Useful in pagination. Will show the total number of results, for example if the request is limited to returning 25 maps:

"meta": {
  "total_entries": 50,
  "total_pages": 2
}

List User Activity

Lists all activity for one user, ordered by created_at desc Authentication required.

Method Definition
GET /api/v1/activity/users/{:id}

Parameters

Name Type Description Required Notes
id integer unique identifier of the user required
page integer the page number; use to get the next or previous page of search results optional
per_page integer number of results per page optional default is 50

cURL Example

curl -H "Content-Type: application/json" -H 'Accept: application/json' -X GET  http://mapwarper.net/api/v1/activity/users/3?per_page=2 -b cookie

Response

{
	"data": [
		{
			"id": 2148,
			"auditable_id": 287,
			"auditable_type": "Map",
			"user_id": 2,
			"action": "update",
			"version": 3,
			"created_at": "2016-05-03T12:14:11.872Z"
		},
		{
			"id": 2147,
			"auditable_id": 287,
			"auditable_type": "Map",
			"user_id": 2,
			"action": "update",
			"version": 2,
			"created_at": "2016-05-03T12:14:11.607Z"
		}
	],
	"meta": {
		"total_entries": 1755,
		"total_pages": 878
	}
}

Response Elements

Data

Name Type Description Notes
id integer unique identifier of the activity
auditable_id integer unique identifier of the item the activity refers to
auditable_type string The type ofitem the activity refers to
user_id integer unique identifier of the user doing the action
action string the type of action one of: "create", "update", "destroy"
version integer the version of the item e.g. a created map will always be version 1 initially
created_at datetime the time of the action

Meta

Useful in pagination. Will show the total number of results, for example if the request is limited to returning 25 maps:

"meta": {
  "total_entries": 50,
  "total_pages": 2
}