Map Layer Management

Overview

The Map Layer Management API  allows external users the capability to manage their Spatial Layer objects in RapidSOS.

  • The API is a programmatic interface with no GUI
  • All endpoints are authenticated via OAuth 2.0.
  • The API provides basic CRUD capabilities for Spatial Layers + Spatial Objects that are 'owned' by the organization accessing them.

Detailed steps to create, edit, and delete the spatial object resources using the RapidSOS Layer Management API are provided below.

Note: This document will not go into detail regarding request or response payload structure. Refer to the Map Layer Management Reference documentation for request, response, and schema details.

Pre-Requisites

Prior to accessing the Map Layer Management API, please ensure the following action items are complete:

  1. Credentials have been provisioned for your company to access the following RapidSOS APIs:

    • Layer Management - for managing spatial layer resources.

    • Resource Manager - for uploading documents to RapidSOS.

      • Note: If your company does not plan to upload file-type resources accessible by emergency telecommunicators, you do not need access to the Resource Manager.

  2. A Spatial Layer for your company has been created by RapidSOS. The Spatial Layer serves as the container for all spatial layer resources related to your company.

    • Without a Spatial Layer, one cannot upload any spatial layer resources.

  3. Access https://editor.swagger.io (or similar OpenAPI parser) - an OpenAPI specification for the Map Layer Management API is also provided. The site will help illustrate the expected request and response payloads.

The following tool is recommended but not required for use of this API.

  • Postman - It is recommended to download Postman, thought it is not needed
    • A Postman Collection is provided to aid in the development and understanding of the flow of data in the Layer Management API.

Provisioning

During the provisioning process, RapidSOS will register a layer and provide the partner with a unique  layer_key.  The process is as follows:

  1. RapidSOS approves and creates a layer

  2. Partner is provided access to the Map Layer Management and Dynamic Layers APIs via a single set of credentials for both services.

  3. Layer keys are retrieved from the Map Layer Management API by the Partner and included in the request body of any payloads sent to the Dynamic Layers API.

Note: To inquire about Spatial Layer creation or status, please contact [email protected].

API Requests

Please contact [email protected] for test credentials and confirmation of pre-requisites.

Authentication

Uses RapidSOS standard OAuth2.0, documented here.

Refer to the Map Layers Management API Spec for additional details.

Creating a Spatial Object

  1. Make a GET request GET /layers

    • The response will contain a list of Spatial Layers that belong to your organization. Find the layer you want to add a Spatial Object to and retrieve the ‘id’ value.

  2. Make a POST request POST /layers/{layer_id}/objects where layerId is the value retrieved from step 1.

    • If the request was successful you will receive a ‘200’ response code.

Editing an Existing Spatial Object

  1. Make a GET request GET /layers

    • The response will contain a list of Spatial Layers that belong to your organization. Find the layer you want to add a Spatial Object to and retrieve the ‘id’ value.

  2. Make a GET request GET /layers/{layer_id}/objects

    • The response will contain a list of Spatial Objects that belong to the Spatial Layer with layerId.

    • Find the ‘id’ of the Spatial Object you wish to update.

  3. Make a PATCH request PATCH /layers/{layer_id}/objects/{object_id}

    • The request should only contain the {key: value} you wish to update.

    • If the request was successful you will receive a ‘200’ response code.

Deleting an Existing Spatial Object

  1. Make a GET request GET /layers

    • The response will contain a list of Spatial Layers that belong to your organization. Find the layer you want to add a Spatial Object to and retrieve the ‘id’ value.

  2. Make a GET request GET /layers/{layer_id}/objects

    • The response will contain a list of Spatial Objects that belong to the Spatial Layer with layerId.

    • Find the ‘id’ of the Spatial Object you wish to update.

  3. Make a DELETE request DELETE /layers/{layer_id}/objects/{object_id}

    • If the request was successful you will receive a ‘204’ response code.

Checking the Status of a Spatial Object

If your company has submitted Spatial Object resources for manual creation, you can check the status of the object by doing the following:

  1. Make a GET request GET /layers

    • The response will contain a list of Spatial Layers that belong to your organization. Find the layer you want to add a Spatial Object to and retrieve the ‘id’ value.

  2. Make a request GET /layers/{layer_id}/objects

    • where ‘layerId’ is the value retrieved from step 1.

    • The response will contain a list of Spatial Objects that belong to the Spatial Layer with layerId.

    • Find the ‘id’ of the Spatial Object you wish to evaluate.

      • If the Spatial Object is not present in the list, it has not been created yet. Please contact your RapidSOS Administrator or check again later.

  3. Make a GET request GET /layers/{layer_id}/objects/{object_id}

    • The response, if the object exists, will contain all information related to the spatial object resource.

    • To verify that the Spatial Object resource is active and available:

      • Verify that the attribute active is true

      • Verify that today’s date falls within the date range specified by effective_date and expiry_date.

Creating Custom Spatial Object Attributes

Each spatial object contains a field named attributes. This field’s data is determined by the Spatial Layer’s attributes field. The Spatial Layer attributes field acts as the schema against which the Spatial Object’s attributes are validated.

Spatial Layer Attributes Example:

The corresponding Spatial Object attributes field:

As the example above illustrates, the Spatial Object’s attributes conform to the schema defined in the Spatial Layer’s attributes field.

Note: All custom attributes should be discussed with your RapidSOS Administrator to ensure proper support

Uploading a File-like Resource

If your company intends to provide access to a file-like resource (a PDF, for example), you must first upload a persistent_reference resource to RapidSOS via the Resource Manager API and then provide the URI as an attribute when creating the Spatial Object.

Please Note:

  • Treat the URI returned as you would treat a password. It is sensitive information and could potentially provide unauthorized access to the uploaded resource.
  • When using the URI for Spatial Object creation do not include the ‘ref://’ prefix.
  • After resolving the URI, the response will include a ‘url’ field. The value for this field is a temporary URL pointing to the uploaded resource. The URL remains valid for 60 seconds.