API

Introduction

Cartes.io is a platform that lets you create maps and markers for anything - and it's built atop a powerful API. You can use this API to create maps and markers, as well as get up to date info.

API base:

https://cartes.io/

Use Cases

There are many reasons to use the API. You can create maps and markers for anything, and integrate it wherever you'd like (as long as it's all legal).

You can also automate the placement of markers if your project needs to do so!

Authorization

You can use the API without authorisation. When you create a marker or a map, each will return a token. You must use this token for further actions on the resource.

Authorization for maps

You do not need an API key to create maps. When you create a map via API, it will return the map object with a token field. This token will only be returned once, and is required to edit or delete the resource you just created.

Authorization for markers

Map setting	Required parameter	Type	Description
Anyone can create markers	-	-	-
Only logged in people can create markers	`api_key` or `map_token`	`string`	-
Only the map owner can create markers	`map_token`	`string`	-

If the map settings allow anyone to create markers, you do not need an API key to create markers.

If the map settings allow only logged in people to create markers, you need an API key to create markers. To authenticate an API request, you should provide your API key in the Authorization header.

Regardless of the map settings, you can create markers if you have the map token.

When you create a marker via API, it will return the marker object with a token field. This token will only be returned once, and is required to edit or delete the resource you just created.

Response Status Codes

Cartes.io returns the following status codes in its API:

Status Code	Description
200	`OK`
201	`CREATED`
400	`BAD REQUEST`
404	`NOT FOUND`
500	`INTERNAL SERVER ERROR`

Endpoints

Maps

Get all public maps

GET /api/maps

Create a map

POST /api/maps

Parameter	Type	Rules	Required	Description
`title`	`string`	Max: 191	-	The title of the map
`slug`	`string`	Max: 255	-	The map slug. Currently un-used
`description`	`string`	-	-	The description of the map and its purpose
`privacy`	`string`	Must be one of: `public`, `unlisted`, `private`	-	The privacy level of the map
`users_can_create_markers`	`string`	Must be one of: `yes`, `no`, `only_logged_in`	-	The setting that defines who can create markers

Get a single map

GET /api/maps/{map-uuid}

Sample response from https://cartes.io/api/maps/048eebe4-8dac-46e2-a947-50b6b8062fec:

{
  "slug": "048eebe4-8dac-46e2-a947-50b6b8062fec",
  "title": "Demo map",
  "description": "This map is a demo map, meant to help you try out this website. You can create markers here willy-nilly, but please behave. Information on this map is not real or accurate.",
  "privacy": "public",
  "users_can_create_markers": "yes",
  "options": null,
  "uuid": "048eebe4-8dac-46e2-a947-50b6b8062fec",
  "created_at": "2020-05-03T15:24:48+02:00",
  "updated_at": "2020-11-20T01:59:58+01:00",
  "categories": [
    {
      "id": 13,
      "name": "Wind turbine",
      "icon": "/images/marker-01.svg",
      "markers_count": 1
    }
  ]
}

Edit a single map

PUT /api/maps/{map-id}

Delete a single map

DELETE /api/maps/{map-id}

Markers

Get all markers on a map

GET /api/maps/{map-id}/markers

Parameter	Type	Required	Description
`show_expired`	`Boolean`	-	Show markers that have already expired

Sample response from https://cartes.io/api/maps/048eebe4-8dac-46e2-a947-50b6b8062fec/markers:

[
  {
    "id": 108,
    "location": {
      "type": "Point",
      "coordinates": [
        45.691931857983,
        10.72265625
      ]
    },
    "category_id": 6,
    "created_at": "2020-05-03T15:25:52+02:00",
    "updated_at": "2020-05-03T15:25:52+02:00",
    "description": "Great views from this watch-tower",
    "expires_at": "2021-05-03T18:25:52+02:00",
    "category": {
      "id": 6,
      "name": "Observation point",
      "slug": "observation-point",
      "icon": "/images/marker-01.svg"
    }
  }
]

Create a marker on a map

POST /api/maps/{map-id}/markers

Parameter	Type	Rules	Required	Description
`category`	`int`	Exists in categories	Only if `category_name` is not present	If you know the category ID that you want to use, pass it with this parameter. Otherwise, use `category_name`
`lat`	`numeric`	Between: -90,90	Yes	The lat position of the marker
`lng`	`numeric`	Between: -180,180	Yes	The lng position of the marker
`description`	`string`	Max: 191	-	A description associated with the marker
`category_name`	`string`	Min: 3, Max: 32	Only if `category` is not present	If you don't know the category ID you want to use or you want to create a new category, pass this parameter

Get a single marker on a map

N/A

Edit a marker on a map

PUT /api/maps/{map-id}/markers/{marker-id}

Parameter	Type	Rules	Required	Description
`description`	`string`	Max: 191	-	A description associated with the marker

Mark a marker as spam

PUT /api/maps/{map-id}/markers/{marker-id}

Parameter	Type	Rules	Required	Description
`is_spam`	`boolean`	-	-	Whether or not the marker is spam

Delete a marker on a map

DELETE /api/maps/{map-id}/markers/{marker-id}

Create markers in bulk

POST /api/maps/{map-id}/markers/bulk

Provide an array of markers. This array should contain marker objects with the following formatting/rules:

Parameter	Type	Rules	Required	Description
`category`	`int`	Exists in categories	Only if `category_name` is not present	If you know the category ID that you want to use, pass it with this parameter. Otherwise, use `category_name`
`lat`	`numeric`	Between: -90,90	Yes	The lat position of the marker
`lng`	`numeric`	Between: -180,180	Yes	The lng position of the marker
`description`	`string`	Max: 191	-	A description associated with the marker
`category_name`	`string`	Min: 3, Max: 32	Only if `category` is not present	If you don't know the category ID you want to use or you want to create a new category, pass this parameter
`created_at`	`timestamp`	-	-	When the marker was created
`updated_at`	`timestamp`	-	-	When the marker was updated
`expires_at`	`timestamp`	-	-	When the marker expired

To post markers in bulk, you must create a personal access token in your account settings, and be approved to create markers in bulk. To request approval to use this endpoint, email us.

Attribution and use policy

In any application you make that uses this API, you must attribute Cartes.io in a clear and visible manner. Additionally, if showing category icons, you must attribute Icons8, the icon provider.

Additionally, you must respect the map privacy options. If the privacy is set to unlisted or private, you may not include the map data in indexes, return the data on search pages, or make them public in any manner that compromises the integrity of the privacy setting.

Cartes.io is an open-source mapping API and web-interface created by M Media.

M-Media-Group / Cartes.io Public

API

Pages 2

Clone this wiki locally