Map Layer Management1.0.0

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

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-Requirements

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.
   • Ruby - 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 Ruby.
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. 

 

Additional Recommendations

The following tools 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.

 

Note: To inquire about Spatial Layer creation or status, please contact RapidSOS.

 

Authentication

The service is authenticated via short-lived OAuth 2.0 access tokens that are valid for 1 hour.

You will need to use both the “client credentials” and “password” grant types for obtaining an access token. These can be described as follows:

Client Credentials Grant Type: Used to authenticate your application’s access to the Geospatial API.

Sandbox: https://api-sandbox.rapidsos.com/oauth/token

Production: https://api.rapidsos.com/oauth/token

 

Headers

 

Creating a Spatial Object

1. Make a GET request to ‘https://api.rapidsos.com/v1/layer-mgmt/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 to ‘https://api.rapidsos.com/v1/layer-mgmt/layers/{{layerId}}/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 request to 
   • URL: https://api.rapidsos.com/v1/layer-mgmt/layers/
   • Method: GET
   • 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 to
   
   • URL: https://api.rapidsos.com/v1/layer-mgmt/layers/{layerId}/objects where ‘layerId’ is the value retrieved from step 1. 
   • Method: GET
   • 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 request to
   
   • URL: https://api.rapidsos.com/v1/layer-mgmt/layers/{layerId}/objects/{objectId}
   • Method: PATCH
   • 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 request to 
   • URL: https://api.rapidsos.com/v1/layer-mgmt/layers/
   • Method: GET
   • 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 to
   
   • URL: https://api.rapidsos.com/v1/layer-mgmt/layers/{layerId}/objects where ‘layerId’ is the value retrieved from step 1. 
   • Method: GET
   • 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 request to
   
   • URL: https://api.rapidsos.com/v1/layer-mgmt/layers/{layerId}/objects/{objectId}
   • Method: DELETE
   • 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 request to 
   • URL: https://api.rapidsos.com/v1/layer-mgmt/layers/
   • Method: GET
   • 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 to
   
   • URL: https://api.rapidsos.com/v1/layer-mgmt/layers/{layerId}/objects where ‘layerId’ is the value retrieved from step 1. 
   • Method: GET
   • 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 request to
   
   • URL: https://api.rapidsos.com/v1/layer-mgmt/layers/{layerId}/objects/{objectId}
   • Method: GET
   • 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:

{

“api_key”: {

“required”: true,

“type”: “string”,

“title”: “API Key”

},

“address”: {

“properties”: {

“street_address”: {

“required”: true,

“type”: “string”,

“title”: “Street Address”

},

“country”: {

“required”: true,

“type”: “string”,

“title”: “Country”

},

}

}

}

 

The corresponding Spatial Object attributes field:

{
	“api_key”: “e0c6a0eb12c74832b42c25a7079e154d”,
	“address”: {
		“street_address”: “123 Main Street, Anywhere, NY, 10001”
		“country”: “USA”
	}
}

 

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

 

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 the resource to RapidSOS 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. 

 

Creating a Persistent Reference

Creating a persistent reference will ensure that the resource remains available for the lifetime of the Spatial Object. 

 

1. Make a request to:
   • URL: https://api.rapidsos.com/v1/resources
   • Method: POST
   • Payload: {"file_name": <str: file_name>, "mime_type": <str mime_type>, "mode": "persistent_reference"}
   • The response payload will contain a pre-signed request for uploading the actual file resource.
   • The response will also include a URI that points to the resource uploaded.
     
     • {‘uri’: ‘ref://<str: uri>’}
     • Note: When using the URI for Spatial Object creation do not include the ‘ref://’ prefix. 
2. Construct a post request from the response received in step 1
   
   • URL: response[“signed_request”][“url”]
   • Method: POST
   • Payload: response[“signed_request”][“fields”]
     
     • Be sure to include the actual file data in your request payload as well.
     • Python’s ‘request’ module provides a simple method for uploading file data.
   • The response will include a URI that points to the resource uploaded.
     
     • {‘uri’: ‘ref://<str: uri>’}
     • Note: When using the URI for Spatial Object creation do not include the ‘ref://’ prefix. 
3. Make a request to:
   
   • URL: https://api.rapidsos.com/v1/resource/{uri}/resolve
   • Method: GET
   • The ‘uri’ in the URL listed above is the ‘uri’ value retrieved from the response in Step 1. 
   • 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. 

 

Additional Reference

• Map Layer Management Reference documentation - Provides the OpenAPI specification for Map Layer Management API. Requests, Responses, and Error codes, and Schemas are provided in detail.