Source: https://developers.woosmap.com/products/stores-api/features/zones/

> For clean Markdown of any page, append `.md` to the page URL.

> For a complete documentation index, see https://developers.woosmap.com/llms.txt

# Zones



**Complete API Specification** : [Zones API Reference](/api-reference/zones-api/get-zones/)

## 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](/products/stores-api/features/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)](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) 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](/products/stores-api/features/search/#geographic-search) is for. If you need to manage store data itself rather than zones, see [Data Management](/products/stores-api/features/data-management/).

## API Endpoint

```http
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`. You can also use the `X-Api-Key` header for server-side or mobile authentication.

```shell
# Server-side (write operations - query parameter)
?private_key=YOUR_PRIVATE_KEY

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

# Server-side / Mobile (header)
-H "X-Api-Key: YOUR_PRIVATE_KEY"
```

For complete authentication details and security best practices, see [API Keys Documentation](/api-reference/authentication/).

## 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](#import-zones) | `POST` | `/zones` | `ZoneList` |
| [Update zones](#update-zones) | `PUT` | `/zones` | `ZoneList` |
| [List zones](#list-zones) | `GET` | `/zones` | – |
| [Delete all zones](#delete-all-zones) | `DELETE` | `/zones` | – |
| [Get a zone by ID](#get-a-zone-by-id) | `GET` | `/zones/{zone_id}` | – |
| [Delete a zone by 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`](/products/map-api/reference/1.4/#woosmap.map.stores.StoresSearchRequest) with the `zone` parameter. For REST API usage, add `zone=true` to your [Search Query](/products/stores-api/features/search/) parameters.

See the [Integration Path Guide](/products/stores-api/guides/integration-path/) 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.

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

```javascript
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));
```

```shell
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'
```

```python
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)
```

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

```javascript
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);
});
```

```java
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();
```

```ruby
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.

```shell
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"]
      }
    ]
  }'
```

```shell
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"
      ]
    }
  ]
}'
```

```python
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)
```

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

```javascript
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);
});
```

```java
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();
```

```ruby
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.

```shell
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"]
      }
    ]
  }'
```

```shell
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"
      ]
    }
  ]
}'
```

```python
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)
```

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

```javascript
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);
});
```

```java
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();
```

```ruby
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 |

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

```javascript
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));
```

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

```python
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)
```

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

```javascript
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);
});
```

```java
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();
```

```ruby
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.

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

```javascript
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));
```

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

```python
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)
```

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

```javascript
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);
});
```

```java
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();
```

```ruby
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.

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

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

```python
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)
```

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

```javascript
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);
});
```

```java
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();
```

```ruby
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.

```shell
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

```json
{
  "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",
}
```

```json
{
  "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

## Related Features

- [Search](/products/stores-api/features/search/) - Add `zone=true` to perform zone-based store search
- [Data Management](/products/stores-api/features/data-management/) - Manage the store data that zones are linked to
- [Stores API Overview](/products/stores-api/overview/) - Full overview of Stores API capabilities