API Version: 1
Last updated: 9.11.2020
To start using the API, please email support@inkatlas.com to request an API key for your account.
All API calls should be made as POST requests with a JSON body, unless otherwise specified. JSON responses are returned. Requests must include a key parameter with your API key, unless otherwise specified. API requests that upload files and create maps are subject to usage limits as outlined below.
styles
Fetch a list of map styles available in your account. Each style has a ref property which can be used in create requests. The tileserver and tileserver_retina properties provide tile URLs for this style (both regular resolution and high/retina resolution if available).
Example Request (cURL)
curl -X POST -H "Content-Type: application/json" -d '{"key": "ABC123"}' https://inkatlas.com/api/v1/styles/
Example Response
[
{
"name": "OpenStreetMap",
"ref": "openstreetmap",
"screen_attribution": "OpenStreetMap contributors (openstreetmap.org)",
"tileserver": "http://tile.inkatlas.com/myuser/mystyle/{z}/{x}/{y}.png",
"tileserver_retina": "http://tile2x.inkatlas.com/myuser/mystyle/{z}/{x}/{y}.png"
},
{
"name": "OpenTopoMap",
"ref": "opentopomap-hillshade",
"screen_attribution": "OpenStreetMap contributors (openstreetmap.org), Map style: OpenTopoMap (CC-BY-SA)",
"tileserver": "https://{s}.tile.opentopomap.org/{z}/{x}/{y}.png",
"tileserver_retina": null
}
]
layouts
Fetch a list of print layouts available in your account. Each layout has a ref property which can be used in check and create requests.
Example Request (cURL)
curl -X POST -H "Content-Type: application/json" -d '{"key": "ABC123"}' https://inkatlas.com/api/v1/layouts/
Example Response
[
{
"height": 3055,
"name": "Letter multi-page",
"ref": "letter",
"width": 2290
},
{
"height": 3260,
"name": "A4 multi-page",
"ref": "a4",
"width": 2230
}
]
scales
Fetch a list of map scales which can be used in check and create requests. Note that maps can also be rendered in an arbitrary scale using the fit_bbox option described below.
Example Request (cURL)
curl -X POST -H "Content-Type: application/json" -d '{"key": "ABC123"}' https://inkatlas.com/api/v1/scales/
Example Response
[
2000000,
1500000,
1250000,
...
7500,
5000,
2500
]
fonts
Fetch a list of fonts which can be used in create requests.
Example Request (cURL)
curl -X POST -H "Content-Type: application/json" -d '{"key": "ABC123"}' https://inkatlas.com/api/v1/fonts/
Example Response
[
{
"name": "Roboto-Bold.ttf",
"ref": "roboto_bold"
},
{
"name": "IndieFlower.ttf",
"ref": "indieflower"
}
]
upload
Upload a single GeoJSON or GPX file. The file will be verified and stored in your uploads. A file_id will be returned so the points or tracks can be added to maps created in the future. This request is submitted as a multipart form. Usage limits: 50 requests/minute, 500 requests/day.
Example Requests (cURL)
curl -X POST -F "key=ABC123" -F "geojson=@alberta.geojson" https://inkatlas.com/api/v1/upload/
curl -X POST -F "key=ABC123" -F "gpx=@mytrack.gpx" https://inkatlas.com/api/v1/upload/
Example Response
{
"file_id": "6J2ILXPP",
"file_name": "alberta.geojson",
"message": null,
"status": 0,
"type": "geojson"
}
check
Create a page layout given the required map parameters, and return a GeoJSON GeometryCollection containing all the page polygons. This allows a user to play with parameters like scale and paper size to create the map they need. The same request can then be sent to the create function to actually generate the map (see below). An array of errors will be returned if parameters are missing or invalid.
Example Request (cURL)
curl -X POST -H "Content-Type: application/json" -d '{
"key": "ABC123",
"style": "openstreetmap",
"scale": 150000,
"paper": "letter",
"orientation": "p",
"bbox": "56.137,-4.803;56.262,-4.803;56.262,-4.625;56.137,-4.625",
"fit_bbox": false
}' https://inkatlas.com/api/v1/check/
The bbox (bounding box) should contain latitude, longitude pairs separated by semicolons. At least 4 are required to create a valid polygon, but there is no limit and the shape does not need to be a simple rectangle. This is the region that should be mapped, and will be covered entirely by the map page(s) in the layout.
If fit_bbox is enabled, the map area will match the bounding box exactly but the map scale will be adjusted if needed. Otherwise the requested scale will be preserved and the final map area may be larger (but never smaller) than the requested bounding box.
Example Response
{
"pages": {
"geometries": [
{
"coordinates": [
[
[-4.947937021944479, 56.02426620102663],
[-4.947937021944479, 56.37336240778344],
[-4.477551436042595, 56.37336240778344],
[-4.477551436042595, 56.02426620102663],
[-4.947937021944479, 56.02426620102663]
]
],
"type": "Polygon"
}
],
"type": "GeometryCollection"
},
"scale": 150000,
"status": 0
}
Possible status codes:
- 0: layout created successfully
- 1: selected area is too large (area, scale, paper size or orientation should be adjusted)
- 2: map data is missing in part of the selected area (this should never happen)
- 3: elevation data is missing in part of the selected area (this only happens in polar regions)
create
Create a new map and fetch its map_id, which can be used to query its status and download it when it is ready. An array of errors will be returned if parameters are missing or invalid. Usage limits: 50 requests/minute, 500 requests/day.
Example Request (cURL)
curl -X POST -H "Content-Type: application/json" -d '{
"key": "ABC123",
"title": "My New Map",
"description": "My description.",
"style": "openstreetmap",
"scale": 150000,
"paper": "letter",
"orientation": "p",
"bbox": "56.137,-4.803;56.262,-4.803;56.262,-4.625;56.137,-4.625",
"include_index": true,
"enable_leader_lines": true,
"geojson": "JQCX1HPL;45LG2DF4",
"fit_bbox": false,
"scale_factor": 2.5
}' https://inkatlas.com/api/v1/create/
The bbox (bounding box) should contain latitude, longitude pairs separated by semicolons. At least 4 are required to create a valid polygon, but there is no limit and the shape does not need to be a simple rectangle. This is the region that should be mapped, and will be covered entirely by the map page(s) in the layout. Multiple GeoJSON and GPX files can be provided (separated by semicolons).
For a custom map size, paper should be set to custom and additional width and height parameters are required to specify the dimensions of the image in pixels.
The scale_factor option adjusts font size and line width. A higher value means larger labels and thicker streets. 1.0 - 6.0 are acceptable values, 2.0 is a reasonable default.
Example Response
{
"map_id": "YTN5ITM",
"status": 0
}
Custom markers
A custom marker (SVG or PNG) can be used to identify points in your dataset(s). It can be included in the create request as follows:
"marker": "--- base64-encoded SVG here ---",
"marker_format": "svg",
"marker_height": 50,
"marker_width": 20
SVG markers should be used for best results. If marker_height and marker_width are ommitted, the marker will be used as is (no scaling).
Custom fonts
To specify a font that should be used for the title and description in the layout, use the font option:
"font": "roboto_bold"
Use the fonts endpoint to fetch a list of available fonts, or review the list below. Any TTF font can be added on request.
status
Fetch the status of a map and its legacy* download URL (once available). This function can be used to poll the service until a map is ready. No API key is required.
Example Request (cURL)
curl https://inkatlas.com/api/v1/status/YTN5ITM
DEPRECATED:
curl -X POST -H "Content-Type: application/json" -d '{"map_id": "YTN5ITM"}' https://inkatlas.com/api/v1/status/
Example Response
{
"state": "ready",
"url": "/map/YTN5ITM/download/"
}
🛈 *This download URL is provided for backwards compatibility only. Please use the download function instead.
download
Download the final map file. Format was provided by the client in the create request (always PDF for multi-page maps).
Example Request (cURL)
curl https://inkatlas.com/api/v1/download/YTN5ITM > YTN5ITM.png
Example Response
Map file (binary).
🛈 Clients should be prepared to handle redirects when making this request.
delete
Delete one of your maps. This cannot be undone.
Example Request (cURL)
curl -X POST -H "Content-Type: application/json" -d '"key": "ABC123"' https://inkatlas.com/api/v1/delete/YTN5ITM
Example Response
{
"map_id": "YTN5ITM",
"deleted": true
}