February 13, 2019

API Quickstart

Used for sending data on Woosmap servers

1. Presentation
2. Structure of requests
3. Managing assets data
4. Usage limits

Presentation

Public and Private keys

Upon signing up to Woosmap, you will have access to the API key management interface in each project.

key	Description
private_key1	A private key is used for server api calls (POST, PUT and DELETE) where modification of the data occurs.
key	A public key is used client side to fetch your project data.

REST API

Where possible the API strives to use appropriate HTTP verbs for each action.

Verb	Description
GET	Used for retrieving resources.
POST	Used for creating resources.
PUT	Used for replacing resources or collections.
DELETE	Used for deleting resources.

Error Handling

Code	Description
20X	Indicates success or object creation.
403	if Unauthorized
400	if the request data is wrong.

Additionally the answer might contain a message key, with a human error message as the value.

Structure of requests

All data sent and received are in JSON format.

Data sent

The data sent through POST and PUT methods should be in the following format:

JSON

        {
  "stores": [
    {
      "storeId": "unique identifier",
      "name": "Store Name",
      "location": {
        "lat": 43.600,
        "lng": 3.883
      }
    }
  ]
}

    

Each element of the stores array must be in the format explained here .

Managing assets data

The restrictions on POST and PUT on storeIds are made to ensure identifier stability.

Create assets data

Used to create assets in batch.

Warning: storeId must not exist when using POST method, if one store already exists, the batch will be refused.

Sample create request

URL

cURL

NodeJS

Python

Java

Ruby

        https://api.woosmap.com/stores
  ?private_key=YOUR_PRIVATE_API_KEY
    

        curl -L -X POST 'https://api.woosmap.com/stores?private_key=YOUR_PRIVATE_API_KEY' \
-H 'content-type: application/json' \
--data-raw '{
  "stores": [
    {
      "storeId": "store_123",
      "name": "My first cool store",
      "location": {
        "lat": 43.61,
        "lng": 3.88
      }
    }
  ]
}'

    

        var axios = require('axios');
var data = JSON.stringify({
  "stores": [
    {
      "storeId": "store_123",
      "name": "My first cool store",
      "location": {
        "lat": 43.61,
        "lng": 3.88
      }
    }
  ]
});

var config = {
  method: 'post',
  url: 'https://api.woosmap.com/stores?private_key=YOUR_PRIVATE_API_KEY',
  headers: { 
    'content-type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});


    

        import requests
import json

url = "https://api.woosmap.com/stores?private_key=YOUR_PRIVATE_API_KEY"

payload = json.dumps({
    "stores": [
        {
            "storeId": "store_123",
            "name": "My first cool store",
            "location": {
                "lat": 43.61,
                "lng": 3.88
            }
        }
    ]
})
headers = {
    'content-type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)


    

        OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"stores\": [\n    {\n      \"storeId\": \"store_123\",\n      \"name\": \"My first cool store\",\n      \"location\": {\n        \"lat\": 43.61,\n        \"lng\": 3.88\n      }\n    }\n  ]\n}");
Request request = new Request.Builder()
  .url("https://api.woosmap.com/stores?private_key=YOUR_PRIVATE_API_KEY")
  .method("POST", body)
  .addHeader("content-type", "application/json")
  .build();
Response response = client.newCall(request).execute();

    

        require "uri"
require "json"
require "net/http"

url = URI("https://api.woosmap.com/stores?private_key=YOUR_PRIVATE_API_KEY")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["content-type"] = "application/json"
request.body = JSON.dump({
  "stores": [
    {
      "storeId": "store_123",
      "name": "My first cool store",
      "location": {
        "lat": 43.61,
        "lng": 3.88
      }
    }
  ]
})

response = https.request(request)
puts response.read_body


    

Updating assets data

Used to update assets.

Warning: storeId must exist when using PUT method, if one asset does not exist, the batch will be refused.

Sample update request

URL

cURL

NodeJS

Python

Java

Ruby

        https://api.woosmap.com/stores
  ?private_key=YOUR_PRIVATE_API_KEY
    

        curl -L -X PUT 'https://api.woosmap.com/stores?private_key=YOUR_PRIVATE_API_KEY' \
-H 'content-type: application/json' \
--data-raw '{
  "stores": [
    {
      "storeId": "store_123",
      "name": "My amazing store",
      "location": {
        "lat": 43.61,
        "lng": 3.88
      }
    }
  ]
}'

    

        var axios = require('axios');
var data = JSON.stringify({
  "stores": [
    {
      "storeId": "store_123",
      "name": "My amazing store",
      "location": {
        "lat": 43.61,
        "lng": 3.88
      }
    }
  ]
});

var config = {
  method: 'put',
  url: 'https://api.woosmap.com/stores?private_key=YOUR_PRIVATE_API_KEY',
  headers: { 
    'content-type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});


    

        import requests
import json

url = "https://api.woosmap.com/stores?private_key=YOUR_PRIVATE_API_KEY"

payload = json.dumps({
    "stores": [
        {
            "storeId": "store_123",
            "name": "My amazing store",
            "location": {
                "lat": 43.61,
                "lng": 3.88
            }
        }
    ]
})
headers = {
    'content-type': 'application/json'
}

response = requests.request("PUT", url, headers=headers, data=payload)

print(response.text)


    

        OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"stores\": [\n    {\n      \"storeId\": \"store_123\",\n      \"name\": \"My amazing store\",\n      \"location\": {\n        \"lat\": 43.61,\n        \"lng\": 3.88\n      }\n    }\n  ]\n}");
Request request = new Request.Builder()
  .url("https://api.woosmap.com/stores?private_key=YOUR_PRIVATE_API_KEY")
  .method("PUT", body)
  .addHeader("content-type", "application/json")
  .build();
Response response = client.newCall(request).execute();

    

        require "uri"
require "json"
require "net/http"

url = URI("https://api.woosmap.com/stores?private_key=YOUR_PRIVATE_API_KEY")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Put.new(url)
request["content-type"] = "application/json"
request.body = JSON.dump({
  "stores": [
    {
      "storeId": "store_123",
      "name": "My amazing store",
      "location": {
        "lat": 43.61,
        "lng": 3.88
      }
    }
  ]
})

response = https.request(request)
puts response.read_body


    

Deleting assets

You can delete one or more assets using the following example, the storeId is the id you defined. To delete several assets, use the comma as a separator.

Sample delete request

URL

cURL

NodeJS

Python

Java

Ruby

        https://api.woosmap.com/stores/
  ?private_key=YOUR_PRIVATE_API_KEY
  &query=idstore%3A%3Dstore_123
    

        curl -L -X DELETE 'https://api.woosmap.com/stores/?query=idstore%3A%3Dstore_123&private_key=YOUR_PRIVATE_API_KEY'

    

        var axios = require('axios');

var config = {
  method: 'delete',
  url: 'https://api.woosmap.com/stores/?query=idstore%3A%3Dstore_123&private_key=YOUR_PRIVATE_API_KEY',
  headers: { }
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});


    

        import requests

url = "https://api.woosmap.com/stores/?query=idstore%3A%3Dstore_123&private_key=YOUR_PRIVATE_API_KEY"

payload={}
headers = {}

response = requests.request("DELETE", url, headers=headers, data=payload)

print(response.text)


    

        OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://api.woosmap.com/stores/?query=idstore%3A%3Dstore_123&private_key=YOUR_PRIVATE_API_KEY")
  .method("DELETE", body)
  .build();
Response response = client.newCall(request).execute();

    

        require "uri"
require "net/http"

url = URI("https://api.woosmap.com/stores/?query=idstore%3A%3Dstore_123&private_key=YOUR_PRIVATE_API_KEY")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = https.request(request)
puts response.read_body


    

Replace all assets

You can replace all assets of a Project using the following example.

Sample replace request

URL

cURL

NodeJS

Python

Java

Ruby

        https://api.woosmap.com/stores/replace
  ?private_key=YOUR_PRIVATE_API_KEY
    

        curl -L -X POST 'https://api.woosmap.com/stores/replace?private_key=YOUR_PRIVATE_API_KEY' \
-H 'content-type: application/json' \
--data-raw '{
  "stores": [
    {
      "storeId": "store_123",
      "name": "My first cool store",
      "location": {
        "lat": 43.61,
        "lng": 3.88
      }
    }
  ]
}'

    

        var axios = require('axios');
var data = JSON.stringify({
  "stores": [
    {
      "storeId": "store_123",
      "name": "My first cool store",
      "location": {
        "lat": 43.61,
        "lng": 3.88
      }
    }
  ]
});

var config = {
  method: 'post',
  url: 'https://api.woosmap.com/stores/replace?private_key=YOUR_PRIVATE_API_KEY',
  headers: { 
    'content-type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});


    

        import requests
import json

url = "https://api.woosmap.com/stores/replace?private_key=YOUR_PRIVATE_API_KEY"

payload = json.dumps({
    "stores": [
        {
            "storeId": "store_123",
            "name": "My first cool store",
            "location": {
                "lat": 43.61,
                "lng": 3.88
            }
        }
    ]
})
headers = {
    'content-type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)


    

        OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"stores\": [\n    {\n      \"storeId\": \"store_123\",\n      \"name\": \"My first cool store\",\n      \"location\": {\n        \"lat\": 43.61,\n        \"lng\": 3.88\n      }\n    }\n  ]\n}");
Request request = new Request.Builder()
  .url("https://api.woosmap.com/stores/replace?private_key=YOUR_PRIVATE_API_KEY")
  .method("POST", body)
  .addHeader("content-type", "application/json")
  .build();
Response response = client.newCall(request).execute();

    

        require "uri"
require "json"
require "net/http"

url = URI("https://api.woosmap.com/stores/replace?private_key=YOUR_PRIVATE_API_KEY")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["content-type"] = "application/json"
request.body = JSON.dump({
  "stores": [
    {
      "storeId": "store_123",
      "name": "My first cool store",
      "location": {
        "lat": 43.61,
        "lng": 3.88
      }
    }
  ]
})

response = https.request(request)
puts response.read_body


    

This command will delete all previous assets and import assets from the json file.

During the operation previous assets could always be displayed on map.

If the import failed previous assets will not be deleted.

Usage limits

The following usage limits are in place for the Data API on the stores request:

• Maximum of 10 queries per second (QPS) per Project (so possibly the sum of client-side and server-side queries)

1. The private key holds destructive power hence it should remain private, the public key can be made public since it’s used client side. ↩

‹ Get Started Zones API ›

Was this article helpful?

Have more questions? Submit a request