Zones

Define and manage geographic zones linked to your stores for zone-based search.

Complete API Specification: Zones API Reference

What is the Zones Endpoint?

The Zones Endpoint lets you associate geographic polygons (zones) with your stores. This allows you when searching to return the store whose zone contains a specific point. Unlike distance-based search, which relies on straight-line proximity, zone-based search accounts for real-world boundaries like delivery areas, service regions, or franchise territories.

What It Does

Zone management provides a full set of CRUD operations: import zones in bulk, update existing zones, list all zones in your project, retrieve or delete individual zones by ID, and remove all zones at once. Each zone links a polygon (defined in WKT format) to a specific store via store_id and zone_id.

Once zones are imported, you can search for stores by adding zone=true to your Search request. The API returns stores whose zone polygon intersects the queried location rather than the nearest stores by distance.

How Zones Work

Each zone is defined by three key properties:

store_id — links the zone to an existing asset
zone_id — a unique identifier for the zone within your project
polygon — the geographic boundary, expressed as a WKT (Well-Known Text) string. Note that WKT uses longitude latitude order, which is the opposite of the lat/lng order used in other Stores API parameters.

Key Characteristics

Zone-based search is designed for scenarios where geographic boundaries matter more than proximity. Zones are defined as WKT polygons, can be typed and described for filtering, and each zone_id must be unique within a project. Write operations (import, update, delete) require server-side authentication with a private_key.

When to Use This Endpoint

Distance-based search works well for many use cases; finding the nearest store, ATM, or pickup point. But some scenarios require a different approach:

Delivery areas: A restaurant’s delivery zone depends on road networks, traffic, and business rules; not just straight-line distance. The nearest restaurant may not serve a given address.
Service territories: A field technician covers a specific geographic territory that doesn’t follow simple radius rules.
Sales regions: Each sales representative is assigned a territory polygon, and leads should be routed to the rep whose territory contains the address.
Coverage areas: An ISP or utility provider serves specific neighborhoods, and availability depends on whether an address falls within their coverage polygon.

In all these cases, zones let you model real-world business boundaries rather than relying on distance alone.

Zone Search vs. Distance Search

	Distance Search	Zone Search
How it works	Returns assets sorted by distance from the search point	Returns assets whose zone polygon contains the search point
Best for	“Find the nearest store”	“Which store serves this address?”
Query parameter	Default behavior	`zone=true`

Don’t use Zones for simple proximity-based store search, that’s what geographic filtering is for. If you need to manage store data itself rather than zones, see Data Management.

API Endpoint

        https://api.woosmap.com/zones

Individual zone operations use the path https://api.woosmap.com/zones/{zone_id}.

Authentication

Write operations (POST, PUT, DELETE) require a private_key for server-side authentication. Read operations (GET) accept either a key (public API key) or private_key.

        # Server-side (write operations)
?private_key=YOUR_PRIVATE_KEY

# Client-side (read operations)
?key=YOUR_PUBLIC_KEY

For complete authentication details and security best practices, see API Keys Documentation.

Operations Overview

The Zones endpoint supports the following operations on the /zones collection and individual /zones/{zone_id} resources:

Operation	Method	Path	Body
Import zones	`POST`	`/zones`	`ZoneList`
Update zones	`PUT`	`/zones`	`ZoneList`
List zones	`GET`	`/zones`	–
Delete all zones	`DELETE`	`/zones`	–
Get a zone by ID	`GET`	`/zones/{zone_id}`	–
Delete a zone by ID	`DELETE`	`/zones/{zone_id}`	–

Implementation Options

To perform zone-based search using the JavaScript SDK, use woosmap.map.stores.StoresSearchRequest with the zone parameter. For REST API usage, add zone=true to your Search Query parameters.

See the Integration Path Guide for a comparison of available integration approaches.

Request Examples

Search Stores by Zone

Add zone=true to your search query to find stores whose zone polygon contains the queried location.

        curl "https://api.woosmap.com/stores/search/?lat=48.856&lng=2.352&radius=1000&zone=true&key=YOUR_KEY"

Stores intersecting Zone

URL

cURL

JavaScript

NodeJS

Python

Java

Ruby

            https://api.woosmap.com/stores/search/
  ?lat=51.50976
  &lng=-0.145276
  &zone=true
  &key=YOUR_PUBLIC_API_KEY
    

            curl -L 'https://api.woosmap.com/stores/search/?lat=51.50976&lng=-0.145276&zone=true&key=YOUR_PUBLIC_API_KEY' \
-H 'Referer: http://localhost'

    

            const requestOptions = {
  method: "GET",
  redirect: "follow"
};

fetch("https://api.woosmap.com/stores/search/?lat=51.50976&lng=-0.145276&zone=true&key=YOUR_PUBLIC_API_KEY", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

    

            const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: 'https://api.woosmap.com/stores/search/?lat=51.50976&lng=-0.145276&zone=true&key=YOUR_PUBLIC_API_KEY',
  headers: { 
    'Referer': 'http://localhost'
  }
};

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


    

            import requests

url = "https://api.woosmap.com/stores/search/?lat=51.50976&lng=-0.145276&zone=true&key=YOUR_PUBLIC_API_KEY"

payload = {}
headers = {
    'Referer': 'http://localhost'
}

response = requests.request("GET", 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/search/?lat=51.50976&lng=-0.145276&zone=true&key=YOUR_PUBLIC_API_KEY")
  .method("GET", body)
  .addHeader("Referer", "http://localhost")
  .build();
Response response = client.newCall(request).execute();

    

            require "uri"
require "net/http"

url = URI("https://api.woosmap.com/stores/search/?lat=51.50976&lng=-0.145276&zone=true&key=YOUR_PUBLIC_API_KEY")

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

request = Net::HTTP::Get.new(url)
request["Referer"] = "http://localhost"

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


    

Import Zones

Import one or more zones by sending a POST request with a ZoneList body. Each zone_id must be unique within your project.

        curl -X POST "https://api.woosmap.com/zones/?private_key=YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "zones": [
      {
        "store_id": "store123",
        "zone_id": "delivery_zone_1",
        "polygon": "POLYGON((2.29 48.85, 2.35 48.85, 2.35 48.87, 2.29 48.87, 2.29 48.85))",
        "description": "Delivery area - Central Paris",
        "types": ["delivery"]
      }
    ]
  }'

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

            curl -L 'https://api.woosmap.com/zones?private_key=YOUR_PRIVATE_API_KEY' \
-H 'content-type: application/json' \
-d '{
  "zones": [
    {
      "zone_id": "ZoneA",
      "description": "Delivery Zone for Store A",
      "store_id": "STORE_ID_123456",
      "polygon": "POLYGON ((-122.496116 37.7648181,-122.4954079 37.751518,-122.4635648 37.7530788,-122.4618481 37.7514501,-122.4601315 37.7521288,-122.4565266 37.7513144,-122.4540375 37.7566755,-122.4528359 37.7583041,-122.4515485 37.7595934,-122.4546384 37.774656,-122.4718903 37.7731635,-122.472577 37.772485,-122.4755811 37.7725529,-122.4791001 37.7723493,-122.4793576 37.7713995,-122.4784993 37.769839,-122.4783276 37.7680071,-122.4774693 37.766718,-122.4772118 37.7652931,-122.496116 37.7648181))",
      "types": [
        "delivery"
      ]
    },
    {
      "zone_id": "ZoneB",
      "description": "Delivery Zone for Store B",
      "store_id": "STORE_ID_123456",
      "polygon": "POLYGON ((-122.4546384 37.774656,-122.4515485 37.7595934,-122.4354306 37.7602172,-122.4333707 37.7512596,-122.423071 37.7511239,-122.4242726 37.7687665,-122.4259893 37.7691736,-122.4289075 37.7732444,-122.4306241 37.7850483,-122.4472753 37.7830133,-122.445902 37.7759581,-122.4546384 37.774656))",
      "types": [
        "delivery"
      ]
    },
    {
      "zone_id": "ZoneC",
      "description": "Delivery Zone for Store C",
      "store_id": "STORE_ID_45678",
      "polygon": "POLYGON ((-122.4758889 37.7524995,-122.4751594 37.7321718,-122.4688079 37.7299995,-122.4648597 37.7261979,-122.4519851 37.7228035,-122.4483802 37.7215815,-122.4458053 37.726741,-122.4365356 37.7310857,-122.4315574 37.7324433,-122.4246909 37.7312214,-122.4219444 37.731493,-122.423071 37.7511239,-122.4333707 37.7512596,-122.4354306 37.7602172,-122.4515485 37.7595934,-122.4528628 37.7582744,-122.4540375 37.7566755,-122.4565266 37.7513144,-122.4601315 37.7521288,-122.4618481 37.7514501,-122.4635648 37.7530788,-122.4758889 37.7524995))",
      "types": [
        "delivery"
      ]
    }
  ]
}'

    

            const axios = require('axios');
let data = JSON.stringify({
  "zones": [
    {
      "zone_id": "ZoneA",
      "description": "Delivery Zone for Store A",
      "store_id": "STORE_ID_123456",
      "polygon": "POLYGON ((-122.496116 37.7648181,-122.4954079 37.751518,-122.4635648 37.7530788,-122.4618481 37.7514501,-122.4601315 37.7521288,-122.4565266 37.7513144,-122.4540375 37.7566755,-122.4528359 37.7583041,-122.4515485 37.7595934,-122.4546384 37.774656,-122.4718903 37.7731635,-122.472577 37.772485,-122.4755811 37.7725529,-122.4791001 37.7723493,-122.4793576 37.7713995,-122.4784993 37.769839,-122.4783276 37.7680071,-122.4774693 37.766718,-122.4772118 37.7652931,-122.496116 37.7648181))",
      "types": [
        "delivery"
      ]
    },
    {
      "zone_id": "ZoneB",
      "description": "Delivery Zone for Store B",
      "store_id": "STORE_ID_123456",
      "polygon": "POLYGON ((-122.4546384 37.774656,-122.4515485 37.7595934,-122.4354306 37.7602172,-122.4333707 37.7512596,-122.423071 37.7511239,-122.4242726 37.7687665,-122.4259893 37.7691736,-122.4289075 37.7732444,-122.4306241 37.7850483,-122.4472753 37.7830133,-122.445902 37.7759581,-122.4546384 37.774656))",
      "types": [
        "delivery"
      ]
    },
    {
      "zone_id": "ZoneC",
      "description": "Delivery Zone for Store C",
      "store_id": "STORE_ID_45678",
      "polygon": "POLYGON ((-122.4758889 37.7524995,-122.4751594 37.7321718,-122.4688079 37.7299995,-122.4648597 37.7261979,-122.4519851 37.7228035,-122.4483802 37.7215815,-122.4458053 37.726741,-122.4365356 37.7310857,-122.4315574 37.7324433,-122.4246909 37.7312214,-122.4219444 37.731493,-122.423071 37.7511239,-122.4333707 37.7512596,-122.4354306 37.7602172,-122.4515485 37.7595934,-122.4528628 37.7582744,-122.4540375 37.7566755,-122.4565266 37.7513144,-122.4601315 37.7521288,-122.4618481 37.7514501,-122.4635648 37.7530788,-122.4758889 37.7524995))",
      "types": [
        "delivery"
      ]
    }
  ]
});

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

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


    

            import requests
import json

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

payload = json.dumps({
    "zones": [
        {
            "zone_id": "ZoneA",
            "description": "Delivery Zone for Store A",
            "store_id": "STORE_ID_123456",
            "polygon": "POLYGON ((-122.496116 37.7648181,-122.4954079 37.751518,-122.4635648 37.7530788,-122.4618481 37.7514501,-122.4601315 37.7521288,-122.4565266 37.7513144,-122.4540375 37.7566755,-122.4528359 37.7583041,-122.4515485 37.7595934,-122.4546384 37.774656,-122.4718903 37.7731635,-122.472577 37.772485,-122.4755811 37.7725529,-122.4791001 37.7723493,-122.4793576 37.7713995,-122.4784993 37.769839,-122.4783276 37.7680071,-122.4774693 37.766718,-122.4772118 37.7652931,-122.496116 37.7648181))",
            "types": [
                "delivery"
            ]
        },
        {
            "zone_id": "ZoneB",
            "description": "Delivery Zone for Store B",
            "store_id": "STORE_ID_123456",
            "polygon": "POLYGON ((-122.4546384 37.774656,-122.4515485 37.7595934,-122.4354306 37.7602172,-122.4333707 37.7512596,-122.423071 37.7511239,-122.4242726 37.7687665,-122.4259893 37.7691736,-122.4289075 37.7732444,-122.4306241 37.7850483,-122.4472753 37.7830133,-122.445902 37.7759581,-122.4546384 37.774656))",
            "types": [
                "delivery"
            ]
        },
        {
            "zone_id": "ZoneC",
            "description": "Delivery Zone for Store C",
            "store_id": "STORE_ID_45678",
            "polygon": "POLYGON ((-122.4758889 37.7524995,-122.4751594 37.7321718,-122.4688079 37.7299995,-122.4648597 37.7261979,-122.4519851 37.7228035,-122.4483802 37.7215815,-122.4458053 37.726741,-122.4365356 37.7310857,-122.4315574 37.7324433,-122.4246909 37.7312214,-122.4219444 37.731493,-122.423071 37.7511239,-122.4333707 37.7512596,-122.4354306 37.7602172,-122.4515485 37.7595934,-122.4528628 37.7582744,-122.4540375 37.7566755,-122.4565266 37.7513144,-122.4601315 37.7521288,-122.4618481 37.7514501,-122.4635648 37.7530788,-122.4758889 37.7524995))",
            "types": [
                "delivery"
            ]
        }
    ]
})
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  \"zones\": [\n    {\n      \"zone_id\": \"ZoneA\",\n      \"description\": \"Delivery Zone for Store A\",\n      \"store_id\": \"STORE_ID_123456\",\n      \"polygon\": \"POLYGON ((-122.496116 37.7648181,-122.4954079 37.751518,-122.4635648 37.7530788,-122.4618481 37.7514501,-122.4601315 37.7521288,-122.4565266 37.7513144,-122.4540375 37.7566755,-122.4528359 37.7583041,-122.4515485 37.7595934,-122.4546384 37.774656,-122.4718903 37.7731635,-122.472577 37.772485,-122.4755811 37.7725529,-122.4791001 37.7723493,-122.4793576 37.7713995,-122.4784993 37.769839,-122.4783276 37.7680071,-122.4774693 37.766718,-122.4772118 37.7652931,-122.496116 37.7648181))\",\n      \"types\": [\n        \"delivery\"\n      ]\n    },\n    {\n      \"zone_id\": \"ZoneB\",\n      \"description\": \"Delivery Zone for Store B\",\n      \"store_id\": \"STORE_ID_123456\",\n      \"polygon\": \"POLYGON ((-122.4546384 37.774656,-122.4515485 37.7595934,-122.4354306 37.7602172,-122.4333707 37.7512596,-122.423071 37.7511239,-122.4242726 37.7687665,-122.4259893 37.7691736,-122.4289075 37.7732444,-122.4306241 37.7850483,-122.4472753 37.7830133,-122.445902 37.7759581,-122.4546384 37.774656))\",\n      \"types\": [\n        \"delivery\"\n      ]\n    },\n    {\n      \"zone_id\": \"ZoneC\",\n      \"description\": \"Delivery Zone for Store C\",\n      \"store_id\": \"STORE_ID_45678\",\n      \"polygon\": \"POLYGON ((-122.4758889 37.7524995,-122.4751594 37.7321718,-122.4688079 37.7299995,-122.4648597 37.7261979,-122.4519851 37.7228035,-122.4483802 37.7215815,-122.4458053 37.726741,-122.4365356 37.7310857,-122.4315574 37.7324433,-122.4246909 37.7312214,-122.4219444 37.731493,-122.423071 37.7511239,-122.4333707 37.7512596,-122.4354306 37.7602172,-122.4515485 37.7595934,-122.4528628 37.7582744,-122.4540375 37.7566755,-122.4565266 37.7513144,-122.4601315 37.7521288,-122.4618481 37.7514501,-122.4635648 37.7530788,-122.4758889 37.7524995))\",\n      \"types\": [\n        \"delivery\"\n      ]\n    }\n  ]\n}");
Request request = new Request.Builder()
  .url("https://api.woosmap.com/zones?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/zones?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({
  "zones": [
    {
      "zone_id": "ZoneA",
      "description": "Delivery Zone for Store A",
      "store_id": "STORE_ID_123456",
      "polygon": "POLYGON ((-122.496116 37.7648181,-122.4954079 37.751518,-122.4635648 37.7530788,-122.4618481 37.7514501,-122.4601315 37.7521288,-122.4565266 37.7513144,-122.4540375 37.7566755,-122.4528359 37.7583041,-122.4515485 37.7595934,-122.4546384 37.774656,-122.4718903 37.7731635,-122.472577 37.772485,-122.4755811 37.7725529,-122.4791001 37.7723493,-122.4793576 37.7713995,-122.4784993 37.769839,-122.4783276 37.7680071,-122.4774693 37.766718,-122.4772118 37.7652931,-122.496116 37.7648181))",
      "types": [
        "delivery"
      ]
    },
    {
      "zone_id": "ZoneB",
      "description": "Delivery Zone for Store B",
      "store_id": "STORE_ID_123456",
      "polygon": "POLYGON ((-122.4546384 37.774656,-122.4515485 37.7595934,-122.4354306 37.7602172,-122.4333707 37.7512596,-122.423071 37.7511239,-122.4242726 37.7687665,-122.4259893 37.7691736,-122.4289075 37.7732444,-122.4306241 37.7850483,-122.4472753 37.7830133,-122.445902 37.7759581,-122.4546384 37.774656))",
      "types": [
        "delivery"
      ]
    },
    {
      "zone_id": "ZoneC",
      "description": "Delivery Zone for Store C",
      "store_id": "STORE_ID_45678",
      "polygon": "POLYGON ((-122.4758889 37.7524995,-122.4751594 37.7321718,-122.4688079 37.7299995,-122.4648597 37.7261979,-122.4519851 37.7228035,-122.4483802 37.7215815,-122.4458053 37.726741,-122.4365356 37.7310857,-122.4315574 37.7324433,-122.4246909 37.7312214,-122.4219444 37.731493,-122.423071 37.7511239,-122.4333707 37.7512596,-122.4354306 37.7602172,-122.4515485 37.7595934,-122.4528628 37.7582744,-122.4540375 37.7566755,-122.4565266 37.7513144,-122.4601315 37.7521288,-122.4618481 37.7514501,-122.4635648 37.7530788,-122.4758889 37.7524995))",
      "types": [
        "delivery"
      ]
    }
  ]
})

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


    

Update Zones

Update existing zones by sending a PUT request with a ZoneList body. The zones must already exist to be updated.

        curl -X PUT "https://api.woosmap.com/zones/?private_key=YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "zones": [
      {
        "store_id": "store123",
        "zone_id": "delivery_zone_1",
        "polygon": "POLYGON((2.28 48.84, 2.36 48.84, 2.36 48.88, 2.28 48.88, 2.28 48.84))",
        "description": "Delivery area - Expanded Central Paris",
        "types": ["delivery"]
      }
    ]
  }'

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

            curl -L -X PUT 'https://api.woosmap.com/zones?private_key=YOUR_PRIVATE_API_KEY' \
-H 'content-type: application/json' \
-d '{
  "zones": [
    {
      "zone_id": "ZoneA",
      "description": "Delivery Zone for Store A",
      "store_id": "STORE_ID_45678",
      "polygon": "POLYGON ((-122.496116 37.7648181,-122.4954079 37.751518,-122.4635648 37.7530788,-122.4618481 37.7514501,-122.4601315 37.7521288,-122.4565266 37.7513144,-122.4540375 37.7566755,-122.4528359 37.7583041,-122.4515485 37.7595934,-122.4546384 37.774656,-122.4718903 37.7731635,-122.472577 37.772485,-122.4755811 37.7725529,-122.4791001 37.7723493,-122.4793576 37.7713995,-122.4784993 37.769839,-122.4783276 37.7680071,-122.4774693 37.766718,-122.4772118 37.7652931,-122.496116 37.7648181))",
      "types": [
        "delivery"
      ]
    }
  ]
}'

    

            const axios = require('axios');
let data = JSON.stringify({
  "zones": [
    {
      "zone_id": "ZoneA",
      "description": "Delivery Zone for Store A",
      "store_id": "STORE_ID_45678",
      "polygon": "POLYGON ((-122.496116 37.7648181,-122.4954079 37.751518,-122.4635648 37.7530788,-122.4618481 37.7514501,-122.4601315 37.7521288,-122.4565266 37.7513144,-122.4540375 37.7566755,-122.4528359 37.7583041,-122.4515485 37.7595934,-122.4546384 37.774656,-122.4718903 37.7731635,-122.472577 37.772485,-122.4755811 37.7725529,-122.4791001 37.7723493,-122.4793576 37.7713995,-122.4784993 37.769839,-122.4783276 37.7680071,-122.4774693 37.766718,-122.4772118 37.7652931,-122.496116 37.7648181))",
      "types": [
        "delivery"
      ]
    }
  ]
});

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

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


    

            import requests
import json

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

payload = json.dumps({
    "zones": [
        {
            "zone_id": "ZoneA",
            "description": "Delivery Zone for Store A",
            "store_id": "STORE_ID_45678",
            "polygon": "POLYGON ((-122.496116 37.7648181,-122.4954079 37.751518,-122.4635648 37.7530788,-122.4618481 37.7514501,-122.4601315 37.7521288,-122.4565266 37.7513144,-122.4540375 37.7566755,-122.4528359 37.7583041,-122.4515485 37.7595934,-122.4546384 37.774656,-122.4718903 37.7731635,-122.472577 37.772485,-122.4755811 37.7725529,-122.4791001 37.7723493,-122.4793576 37.7713995,-122.4784993 37.769839,-122.4783276 37.7680071,-122.4774693 37.766718,-122.4772118 37.7652931,-122.496116 37.7648181))",
            "types": [
                "delivery"
            ]
        }
    ]
})
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  \"zones\": [\n    {\n      \"zone_id\": \"ZoneA\",\n      \"description\": \"Delivery Zone for Store A\",\n      \"store_id\": \"STORE_ID_45678\",\n      \"polygon\": \"POLYGON ((-122.496116 37.7648181,-122.4954079 37.751518,-122.4635648 37.7530788,-122.4618481 37.7514501,-122.4601315 37.7521288,-122.4565266 37.7513144,-122.4540375 37.7566755,-122.4528359 37.7583041,-122.4515485 37.7595934,-122.4546384 37.774656,-122.4718903 37.7731635,-122.472577 37.772485,-122.4755811 37.7725529,-122.4791001 37.7723493,-122.4793576 37.7713995,-122.4784993 37.769839,-122.4783276 37.7680071,-122.4774693 37.766718,-122.4772118 37.7652931,-122.496116 37.7648181))\",\n      \"types\": [\n        \"delivery\"\n      ]\n    }\n  ]\n}");
Request request = new Request.Builder()
  .url("https://api.woosmap.com/zones?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/zones?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({
  "zones": [
    {
      "zone_id": "ZoneA",
      "description": "Delivery Zone for Store A",
      "store_id": "STORE_ID_45678",
      "polygon": "POLYGON ((-122.496116 37.7648181,-122.4954079 37.751518,-122.4635648 37.7530788,-122.4618481 37.7514501,-122.4601315 37.7521288,-122.4565266 37.7513144,-122.4540375 37.7566755,-122.4528359 37.7583041,-122.4515485 37.7595934,-122.4546384 37.774656,-122.4718903 37.7731635,-122.472577 37.772485,-122.4755811 37.7725529,-122.4791001 37.7723493,-122.4793576 37.7713995,-122.4784993 37.769839,-122.4783276 37.7680071,-122.4774693 37.766718,-122.4772118 37.7652931,-122.496116 37.7648181))",
      "types": [
        "delivery"
      ]
    }
  ]
})

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


    

List Zones

List all zones in your project, sorted by zone_id. The default response is limited to 10 zones. Use the limit parameter to retrieve up to 50 zones per request, and offset to paginate through larger datasets.

Parameter	Type	Description
`limit`	`Number`	Number of zones to retrieve per request (max 50, default 10)
`offset`	`Number`	Number of zones to skip, used for pagination through large datasets

        curl "https://api.woosmap.com/zones/?private_key=YOUR_PRIVATE_KEY&limit=20&offset=0"

List Zones

URL

cURL

JavaScript

NodeJS

Python

Java

Ruby

            https://api.woosmap.com/zones/
  ?limit=2
  &offset=1
  &private_key=YOUR_PRIVATE_API_KEY
    

            curl -L 'https://api.woosmap.com/zones/?private_key=YOUR_PRIVATE_API_KEY&limit=2&offset=1'

    

            const requestOptions = {
  method: "GET",
  redirect: "follow"
};

fetch("https://api.woosmap.com/zones/?private_key=YOUR_PRIVATE_API_KEY&limit=2&offset=1", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

    

            const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: 'https://api.woosmap.com/zones/?private_key=YOUR_PRIVATE_API_KEY&limit=2&offset=1',
  headers: { }
};

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


    

            import requests

url = "https://api.woosmap.com/zones/?private_key=YOUR_PRIVATE_API_KEY&limit=2&offset=1"

payload = {}
headers = {}

response = requests.request("GET", 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/zones/?private_key=YOUR_PRIVATE_API_KEY&limit=2&offset=1")
  .method("GET", body)
  .build();
Response response = client.newCall(request).execute();

    

            require "uri"
require "net/http"

url = URI("https://api.woosmap.com/zones/?private_key=YOUR_PRIVATE_API_KEY&limit=2&offset=1")

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

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

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


    

Get a Zone by ID

Retrieve a single zone by passing its zone_id in the URL path.

        curl "https://api.woosmap.com/zones/delivery_zone_1?private_key=YOUR_PRIVATE_KEY"

Get Zone by ID

URL

cURL

JavaScript

NodeJS

Python

Java

Ruby

            https://api.woosmap.com/zones/ZoneA/
  ?private_key=YOUR_PRIVATE_API_KEY
    

            curl -L 'https://api.woosmap.com/zones/ZoneA/?private_key=YOUR_PRIVATE_API_KEY'

    

            const requestOptions = {
  method: "GET",
  redirect: "follow"
};

fetch("https://api.woosmap.com/zones/ZoneA/?private_key=YOUR_PRIVATE_API_KEY", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

    

            const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: 'https://api.woosmap.com/zones/ZoneA/?private_key=YOUR_PRIVATE_API_KEY',
  headers: { }
};

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


    

            import requests

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

payload = {}
headers = {}

response = requests.request("GET", 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/zones/ZoneA/?private_key=YOUR_PRIVATE_API_KEY")
  .method("GET", body)
  .build();
Response response = client.newCall(request).execute();

    

            require "uri"
require "net/http"

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

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

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

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


    

Delete All Zones

Remove all zones from your project.

        curl -X DELETE "https://api.woosmap.com/zones/?private_key=YOUR_PRIVATE_KEY"

            https://api.woosmap.com/zones/
  ?private_key=YOUR_PRIVATE_API_KEY
    
            curl -L -X DELETE 'https://api.woosmap.com/zones/?private_key=YOUR_PRIVATE_API_KEY'

            const axios = require('axios');

let config = {
  method: 'delete',
  maxBodyLength: Infinity,
  url: 'https://api.woosmap.com/zones/?private_key=YOUR_PRIVATE_API_KEY',
  headers: { }
};

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

            import requests

url = "https://api.woosmap.com/zones/?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/zones/?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/zones/?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

Delete a Zone by ID

Delete a single zone by passing its zone_id in the URL path.

        curl -X DELETE "https://api.woosmap.com/zones/delivery_zone_1?private_key=YOUR_PRIVATE_KEY"

Understanding the Response

List Zones Response

Returns a ZoneList object containing an array of zones, sorted by zone_id. If your project contains more than 50 zones, use multiple requests with limit and offset to paginate through all results.

Get Zone by ID Response

Returns a single Zone object with the full polygon, associated store_id, and optional metadata.

Delete Response

Returns a Message object with a status confirmation.

Response Examples

            {
  "store_id": "STORE_ID_123456",
  "zone_id": "ZoneA",
  "polygon": "POLYGON ((-122.496116 37.7648181, -122.4954079 37.751518, -122.4635648 37.7530788, -122.4618481 37.7514501, -122.4601315 37.7521288, -122.4565266 37.7513144, -122.4540375 37.7566755, -122.4528359 37.7583041, -122.4515485 37.7595934, -122.4546384 37.774656, -122.4718903 37.7731635, -122.472577 37.772485, -122.4755811 37.7725529, -122.4791001 37.7723493, -122.4793576 37.7713995, -122.4784993 37.769839, -122.4783276 37.7680071, -122.4774693 37.766718, -122.4772118 37.7652931, -122.496116 37.7648181))",
  "types": ["delivery"],
  "description": "Delivery Zone for Store A",
  "status": "ok",
}

    

            {
  "zones":
    [
      {
        "store_id": "STORE_ID_123456",
        "zone_id": "ZoneB",
        "polygon": "POLYGON ((-122.4546384 37.774656, -122.4515485 37.7595934, -122.4354306 37.7602172, -122.4333707 37.7512596, -122.423071 37.7511239, -122.4242726 37.7687665, -122.4259893 37.7691736, -122.4289075 37.7732444, -122.4306241 37.7850483, -122.4472753 37.7830133, -122.445902 37.7759581, -122.4546384 37.774656))",
        "types": ["delivery"],
        "description": "Delivery Zone for Store B",
      },
      {
        "store_id": "STORE_ID_45678",
        "zone_id": "ZoneC",
        "polygon": "POLYGON ((-122.4758889 37.7524995, -122.4751594 37.7321718, -122.4688079 37.7299995, -122.4648597 37.7261979, -122.4519851 37.7228035, -122.4483802 37.7215815, -122.4458053 37.726741, -122.4365356 37.7310857, -122.4315574 37.7324433, -122.4246909 37.7312214, -122.4219444 37.731493, -122.423071 37.7511239, -122.4333707 37.7512596, -122.4354306 37.7602172, -122.4515485 37.7595934, -122.4528628 37.7582744, -122.4540375 37.7566755, -122.4565266 37.7513144, -122.4601315 37.7521288, -122.4618481 37.7514501, -122.4635648 37.7530788, -122.4758889 37.7524995))",
        "types": ["delivery"],
        "description": "Delivery Zone for Store C",
      },
    ],
  "status": "ok",
}

    

Usage Limits & Quotas

Rate Limit: Shared with Stores API project quotas
Exceeding limits returns 429 Too Many Requests
Contact support for higher quotas

Search - Add zone=true to perform zone-based store search
Data Management - Manage the store data that zones are linked to
Stores API Overview - Full overview of Stores API capabilities

‹ Data Management Integration Path ›

What is the Zones Endpoint?

What It Does

How Zones Work

Key Characteristics

When to Use This Endpoint

Zone Search vs. Distance Search

API Endpoint

Authentication

Operations Overview

Implementation Options

Request Examples

Search Stores by Zone

Import Zones

Update Zones

List Zones

Get a Zone by ID

Delete All Zones

Delete a Zone by ID

Understanding the Response

List Zones Response

Get Zone by ID Response

Delete Response

Response Examples

Usage Limits & Quotas

Related Features