Using the Maps API Follow

Using the Meridian Maps API, you can download the map SVG images from the Editor, make changes to the SVG image, and then upload it back to the Editor.

You can test any Meridian API endpoint by entering that URL in your browser.

Before using the API to upload edited SVG map images, please contact us at maps@meridianapps.com to enable this. If you’re editing map with pre-existing placemarks, routes, and Beacons, please note that it’s very easy to change the scale of a map, distorting placemark, routing, and Beacon locations on the map.

Image Size

SVG map images should be at least 1536px x 2048px

Map Editing Workflow

Using the Meridian Maps REST API, a typical workflow for creating a map would look like the following.

1. Get a valid personal or application token.

All of the following API requests will need to use the token authentication.

2. Send a POST request to the maps endpoint for a specific location to create a new map.

   https://edit.meridianapps.com/api/locations/{Location ID}/maps

3. Send a PUT request to add an SVG map file to a specific maps endpoint.

   https://edit.meridianapps.com/api/locations/{location ID}/maps/<map_id>/svg

Authentication Token

Complete these steps to get a token to authenticate to the Meridian API.

You’ll generate application tokens on the Locations list page. If you’re looking at a specific location, click the Aruba Meridian logo in the top left corner to return to the Locations list page.

1. Once you’ve logged in to the Editor, click the Application Tokens tab.
2. Click Add +.
3. In the NAME field, give the application token a meaningful name.
4. Click Generate Token.
5. In the Permission Type dropdown, choose either Organization or Location. If you select Organization, the token will provide access to all of the locations in that organization.
6. In the new Organization/Location dropdown, browse or search for a specific organization or location.
7. In the Level dropdown choose either Owner or Read-Only. Owner tokens provide read and write access.
8. Click Save.

Token Authentication

Upon receiving successful login credentials, the login API returns a token value. This token is available for use until it’s deleted or a logout request is received.

Download SVG Map Files

In order to download a map in the Editor, send a GET request to the SVG endpoint for a specific location and map ID:

https://edit.meridianapps.com/api/locations/{Location ID}/maps/{Map ID}/svg

You can also download a map using the Editor’s Map Edit interface. If you don’t see the option to download a map, please send an email to maps@meridianapps.com to get that enabled for you.

Upload SVG Map Files

Once you’ve created a map, send a PUT request to the SVG endpoint to upload a file:

https://edit.meridianapps.com/api/locations/{Location ID}/maps/{Map ID}/svg

If your SVG map image doesn’t pass the Editor’s strict SVG validation, the upload will fail.

Add the following string to your request to ignore validation errors and upload the map anyway:

?suppress_svg_errors=True

When you upload a map, make sure to add or adjust the map’s Anchor Points on the map’s Edit Map page.

Upload SVG Example

curl -H "Content-Type: multipart/form-data" -H "Authorization: Token 5b1a4ba3e21147f9064d9278dca729d97141bb45" -X PUT -v -F "svg=@my_svg_map_file.svg" https://edit.meridianapps.com/api/locations/5468665088573440/maps/5095280043098112/svg`

Response:
< HTTP/1.1 200 OK
< content-language: en
< vary: Accept, Accept-Language, Cookie
< allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
< access-control-allow-credentials: false
< access-control-allow-origin: *
< content-type: application/json
< x-meridian-media-type: version=default
< Cache-Control: no-cache
< Content-Length: 165
< Date: Tue, 22 Mar 2016 22:46:44 GMT
<
{"id":"16527005","created":"2016-03-22T22:46:44.515512","content_type":"image/svg+xml","filename":"my_svg_map_file.svg","size":47170,"image_width":1700,"image_height":2200}

SVG URL

Once you’ve uploaded a map SVG file, you can get the SVG URL from:

https://edit.meridianapps.com/api/locations/{Location ID}/maps

or

https://edit.meridianapps.com/api/locations/{Location ID}/maps/{Map ID}

The URL for the map SVG file is located in the svg_url field and has this structure:

https://edit.meridianapps.com/api/locations/{Location ID}/maps/{Map ID}.svg?namespace={location ID}_1&hash={map file hash}&style={map style hash}&default_style={original OR new}

The hash and style hash values will check whether the Editor can return the cached version of the map SVG file or not.

The default_style field takes either original or new. In most cases, use original.

Delete SVG Map Files

In addition to uploading SVG map files, send a DELETE request to an SVG endpoint to remove a map from a location:

https://edit.meridianapps.com/api/locations/{Location ID}/maps/{Map ID}/svg

Delete SVG Example

curl -H "Content-Type: application/json" -H "Authorization: Token 5b1a4ba3e21147f9064d9278dca729d97141bb45" -X DELETE -v https://edit.meridianapps.com/api/locations/5468665088573440/maps/4813805066387456/svg`

Response:
< HTTP/1.1 204 No Content
< content-language: en
< vary: Accept, Accept-Language, Cookie
< allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
< access-control-allow-credentials: false
< access-control-allow-origin: *
< x-meridian-media-type: version=default
< Content-Type: text/html
< Server: Development/2.0
< Date: Tue, 22 Mar 2016 22:35:06 GMT

Adjacent Maps

Maps are often grouped together as levels in a building. You can use the maps endpoint to get maps that are adjacent to a specific map. An adjacent map is one that’s either one level above or below a specific map.

https://edit.meridianapps.com/api/locations/{Location ID}/maps/{Map ID}/adjacent

Maps Endpoint Fields Reference

Here are descriptions of the Maps API endpoint fields.

id

The map’s unique id. This value is auto-generated.

name

The name of the map. REQUIRED

group (READ ONLY)

A numeric ID value. You can use a pre-existing group ID. A grouping of maps, usually organized by building.

group_name

Usually a building name.

level

A number corresponding the map’s floor. Can be an integer or a float.

level_label

A level’s name. This is a character field.

svg

Used for vector (svg) map image files.

To upload a map image or delete a map image, use the following endpoint:

https://edit.meridianapps.com/api/locations/{location_id}/svg/{id}/svg

gps_ref_points

The Meridian Editor uses GPS reference, or control, points corresponding to map reference points to calculate a map’s height, width, and north offset values.

The first four values are the longitude and latitude GPS coordinates for the two reference points. The last four values are the X and Y coordinates for the two reference points on the map.

"gps_ref_points": "45.520548675580265,-122.6730340719223,45.519853330685756,-122.6725673675537,140,379.9999899864197,1553.3333740234375,1859.9998779296875",

If you’re using GPS reference points, there’s no need to manually add height, width, and north offset values.

The Editor needs an SVG map to calculate height and width automatically using GPS reference points. If changes are made to these reference points, the height and width are recalculated.

width_meters

The actual size of the map location width in meters. This value is automatically calculated when GPS reference points have been set, but width_meters can be entered manually. REQUIRED

height_meters

The actual size of the map location height in meters. This value is automatically calculated when GPS reference points have been set, but height_meters can be entered manually. REQUIRED

north

The number of degrees a map is offset, or rotated, from north to rotate the orientation of the map in the Meridian-powered app.

north_offset

The number of degrees a map is offset, or rotated, from north to account for variation from magnetic north.

is_default

If true, this is the map that will be shown first in the Meridian-powered app.

is_outdoor

If true, the map will use a combination of GPS and BLE positioning.

The Meridian team does not recommend creating a map from scratch.

Create a New Map

The Meridian Editor has strict SVG requirements for its maps. The Meridian team doesn’t encourage uploading maps created from scratch. Our Meridian Maps team would be more than happy to create one or more high-quality maps for your location in a timely fashion.

When you use the Meridian API to create one or more maps, you can use some or all of the maps API fields.

To create a map with the API, send a POST request to:

https://edit.meridianapps.com/api/locations/{Location ID}/maps

When you send the request, be sure to include name, width_meters, and height_meters. These are required fields. All other fields are optional.

When you send a POST request without any other included values, the Editor will create a blank “Outdoor Area” map.

Maps Endpoint Fields

The following are the Maps API endpoint fields. The fields in bold are read-only.

“id”: “123456789”,

“name”: “map”,

“group”: “987654321”,

“group_name”: “building”,

“level”: 1,

“level_label”: “Floor 1”,

“image_url”: “http://www.image.com/image.jpg”,

“svg_url”: “http://www.image.com/image.svg”,

“width”: 1700,

“height”: 2200,

“width_meters”: 71.442629694285699,

“height_meters”: 92.455167839663844,

“north_offset”: 35.5,

“gps_ref_points”: “45.1,-122.6,45.5,-122.6,77.3,333.19,1581.1,1896.5”,

“is_default”: false,

“is_outdoor”: true

Map Creation Example

curl -H "Content-Type: application/json" -H "Authorization: Token 5b1a4ba3e21147f9064d9278dca729d97141bb45" -X POST -v -d '{"name": "curl test", "height_meters": 90.5, "width_meters": 70.5}' https://edit.meridianapps.com/api/locations/5468665088573440/maps`

Response:
< HTTP/1.1 201 Created
< content-language: en
< vary: Accept, Accept-Language, Cookie
< allow: GET, POST, HEAD, OPTIONS
< access-control-allow-credentials: false
< access-control-allow-origin: *
< content-type: application/json
< x-meridian-media-type: version=default
< Cache-Control: no-cache
< Expires: Fri, 01 Jan 1990 00:00:00 GMT
< Content-Length: 299
< Server: Development/2.0
< Date: Tue, 22 Mar 2016 22:23:10 GMT
<

{"id":"5254709229125632","name":"curl test","group":"","group_name":"","level":null,"level_label":null,"image_url":null,"svg_url":"","width":null,"height":null,"width_meters":70.5,"height_meters":90.5,"north_offset":0.0,"gps_ref_points":null,"overview_map_id":"","is_default":null,"is_outdoor":null}