Using the Maps API

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.

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.

  1. 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

  2. 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

Personal Tokens

Before you can use the Meridian API Maps endpoint you'll need a token. Send a POST request with your username and password to the login endpoint to receive a personal token.

https://edit.meridianapps.com/api/login

Once you're logged in, you can request another token by sending a POST request to:

https://edit.meridianapps.com/api/tokens

Application Token

If you need a token for an application you're developing, you can generate that token in the Meridian Editor.

Follow these steps to generate or get the application token from the Meridian Editor.

  1. In the Meridian Editor sidebar, click PERMISSIONS.
  2. Click the Application Tokens tab.
  3. Click the Add Application + button.
  4. Enter the application name, and then click OK.
  5. Copy the token value into your application.

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.

For more information on token authentication, please see the Token API article.

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 support@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 GPS control 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.