Skip to main content

Bulk Availability

Get delivery window availability for a zone across a date range. You can specify the zone either by coordinates (lat/lng) or directly by zone ID.

GET /public/delivery-slots/availability/bulk

Request​

Query Parameters​

ParameterTypeRequiredDescription
zoneIdstring (UUID)ConditionalAssignment zone ID. Required if lat/lng are not provided.
latnumberConditionalLatitude (-90 to 90). Required with lng if zoneId is not provided.
lngnumberConditionalLongitude (-180 to 180). Required with lat if zoneId is not provided.
startDatestringYesStart date in YYYY-MM-DD format
endDatestringYesEnd date in YYYY-MM-DD format

Note: You must provide either zoneId OR both lat and lng. If both are provided, zoneId takes precedence.

Headers​

HeaderRequiredDescription
X-API-KeyYesYour API key

Use Cases​

  • Import availability data into ERP systems
  • Plan delivery schedules across multiple days
  • Analyze capacity utilization
  • Build calendar views for customers

Examples​

curl -X GET "https://api.courimax.com/api/public/delivery-slots/availability/bulk?zoneId=d4fc7ec7-1515-42ae-b85d-4ed26376d97a&startDate=2026-08-20&endDate=2026-08-25" \
  -H "X-API-Key: cmx_your_api_key"

By Coordinates​

curl -X GET "https://api.courimax.com/api/public/delivery-slots/availability/bulk?lat=32.0853&lng=34.7818&startDate=2026-08-20&endDate=2026-08-25" \
  -H "X-API-Key: cmx_your_api_key"

JavaScript (Fetch)​

// By Zone ID
const params = new URLSearchParams({
  zoneId: 'd4fc7ec7-1515-42ae-b85d-4ed26376d97a',
  startDate: '2026-08-20',
  endDate: '2026-08-25'
});

// Or by coordinates
// const params = new URLSearchParams({
//   lat: '32.0853',
//   lng: '34.7818',
//   startDate: '2026-08-20',
//   endDate: '2026-08-25'
// });

const response = await fetch(
  `https://api.courimax.com/api/public/delivery-slots/availability/bulk?${params}`,
  {
    headers: {
      'X-API-Key': 'cmx_your_api_key'
    }
  }
);

const availability = await response.json();
console.log(availability);

Python (Requests)​

import requests

# By Zone ID
params = {
    'zoneId': 'd4fc7ec7-1515-42ae-b85d-4ed26376d97a',
    'startDate': '2026-08-20',
    'endDate': '2026-08-25'
}

# Or by coordinates
# params = {
#     'lat': '32.0853',
#     'lng': '34.7818',
#     'startDate': '2026-08-20',
#     'endDate': '2026-08-25'
# }

response = requests.get(
    'https://api.courimax.com/api/public/delivery-slots/availability/bulk',
    headers={
        'X-API-Key': 'cmx_your_api_key'
    },
    params=params
)

availability = response.json()
print(availability)

Response​

Success (200 OK)​

{
  "polygonId": "d4fc7ec7-1515-42ae-b85d-4ed26376d97a",
  "polygonName": "Ben-Yehuda, 32 Extended",
  "dates": [
    {
      "date": "2026-08-20",
      "slots": [
        {
          "templateId": "bb027ac7-2c9c-4c58-bbed-8245f92be86c",
          "label": "שני צהריים",
          "date": "2026-08-20",
          "dayOfWeek": 1,
          "startTime": "10:00",
          "endTime": "13:00",
          "durationMinutes": 180,
          "deliveryWindowStart": "2026-08-20T10:00:00+03:00",
          "deliveryWindowEnd": "2026-08-20T13:00:00+03:00",
          "cutoffAt": "2026-08-20T06:00:00.000Z",
          "capacity": 10,
          "booked": 2,
          "available": 8,
          "bookable": true,
          "vehicleCapacity": [
            {
              "count": 1,
              "vehicleType": "van",
              "maxOrdersPerVehicle": 10
            }
          ]
        }
      ]
    },
    {
      "date": "2026-08-21",
      "slots": []
    }
  ]
}

Response Fields​

FieldTypeDescription
polygonIdstringAssignment zone ID
polygonNamestringAssignment zone name
datesarrayArray of date objects
dates[].datestringDate (YYYY-MM-DD)
dates[].slotsarrayArray of available slots for that date
dates[].slots[].templateIdstringSlot template ID
dates[].slots[].labelstringHuman-readable slot label
dates[].slots[].datestringDate (YYYY-MM-DD)
dates[].slots[].dayOfWeeknumberDay of week (0=Sunday, 6=Saturday)
dates[].slots[].startTimestringStart time (HH:MM)
dates[].slots[].endTimestringEnd time (HH:MM)
dates[].slots[].durationMinutesnumberDuration in minutes
dates[].slots[].deliveryWindowStartstringISO 8601 delivery window start
dates[].slots[].deliveryWindowEndstringISO 8601 delivery window end
dates[].slots[].cutoffAtstringISO 8601 cutoff time
dates[].slots[].capacitynumberMaximum capacity
dates[].slots[].bookednumberNumber of orders booked
dates[].slots[].availablenumberAvailable capacity (capacity - booked)
dates[].slots[].bookablebooleanWhether new orders can be booked
dates[].slots[].vehicleCapacityarrayVehicle capacity configuration

Error Responses​

400 Bad Request - Missing or invalid parameters

{
  "statusCode": 400,
  "message": "Either (lat, lng) or zoneId must be provided",
  "error": "Bad Request"
}
{
  "statusCode": 400,
  "message": "startDate must be before endDate",
  "error": "Bad Request"
}

401 Unauthorized - Missing or invalid API key

{
  "statusCode": 401,
  "message": "Missing X-API-Key header",
  "error": "Unauthorized"
}

404 Not Found - No active zones configured

{
  "statusCode": 404,
  "message": "No active zones found for the given coordinates",
  "error": "Not Found"
}

Data Format​

The response provides a structured array of dates, each containing an array of slots. This makes it easy to:

  • Import into spreadsheet applications
  • Load into ERP systems
  • Build calendar UIs
  • Analyze capacity trends

Filtering Results​

Filter the results client-side based on your needs:

// Get only bookable slots
const bookableSlots = availability.dates.flatMap(d => d.slots).filter(slot => slot.bookable);

// Get slots for a specific date
const mondaySlots = availability.dates.find(d => d.date === '2026-08-20')?.slots || [];

// Get all slots with available capacity
const availableSlots = availability.dates.flatMap(d => d.slots).filter(slot => slot.available > 0);

Performance Considerations​

  • Large date ranges return more data
  • Consider limiting to 7-14 days for optimal performance
  • Cache results when appropriate (data changes as orders are scheduled)

Next Steps​