References API

Fetch the same regions, comunas, and services you see in your panel. Use this to build address selectors in your checkout.

This data rarely changes. Fetch it once and cache it for a day or a week.

GET/regions

Get regions

Get all Chilean regions for your address selector.

Response Fields

Name
id
Type
integer
Description
Unique region identifier.
Name
name
Type
string
Description
Region name.
Name
slug
Type
string
Description
URL-friendly region identifier.
Name
localities_count
Type
integer
Description
Number of localities in this region.

GET

/regions

curl https://api.4nortes.app/api/v1/regions \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Regions retrieved successfully",
  "data": [
    {
      "id": 1,
      "name": "Arica y Parinacota",
      "slug": "arica-y-parinacota",
      "localities_count": 4
    },
    {
      "id": 2,
      "name": "Tarapacá",
      "slug": "tarapaca",
      "localities_count": 7
    },
    {
      "id": 7,
      "name": "Metropolitana de Santiago",
      "slug": "metropolitana-de-santiago",
      "localities_count": 52
    },
    {
      "id": 6,
      "name": "Valparaíso",
      "slug": "valparaiso",
      "localities_count": 38
    }
  ],
  "timestamp": "2025-02-03T10:00:00.000000Z"
}

GET/localities

Get comunas

Get all comunas (localities).

Response Fields

Name
id
Type
integer
Description
Unique locality identifier. Use this when creating orders.
Name
region_id
Type
integer
Description
ID of the region this locality belongs to.
Name
name
Type
string
Description
Locality name (comuna).
Name
slug
Type
string
Description
URL-friendly locality identifier.
Name
type
Type
string
Description
Locality type.
Name
aliases
Type
array
Description
Alternative names for this locality.

GET

/localities

curl https://api.4nortes.app/api/v1/localities \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Localities retrieved successfully",
  "data": [
    {
      "id": 1,
      "region_id": 7,
      "name": "Santiago",
      "slug": "santiago",
      "type": "comuna",
      "aliases": []
    },
    {
      "id": 2,
      "region_id": 7,
      "name": "Providencia",
      "slug": "providencia",
      "type": "comuna",
      "aliases": []
    },
    {
      "id": 3,
      "region_id": 7,
      "name": "Las Condes",
      "slug": "las-condes",
      "type": "comuna",
      "aliases": []
    }
  ],
  "timestamp": "2025-02-03T10:00:00.000000Z"
}

GET/services

Get services

Get the delivery service options.

Response Fields

Name
id
Type
integer
Description
Unique service identifier. Use this when creating orders.
Name
code
Type
string
Description
Service code.
Name
name
Type
string
Description
Service name.
Name
type
Type
string
Description
Service type.

GET

/services

curl https://api.4nortes.app/api/v1/services \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Services retrieved successfully",
  "data": [
    {
      "id": 1,
      "code": "EXPRESS",
      "name": "NextDay Express",
      "type": "express"
    },
    {
      "id": 2,
      "code": "STANDARD",
      "name": "NextDay Standard",
      "type": "standard"
    },
    {
      "id": 3,
      "code": "ECONOMY",
      "name": "NextDay Economy",
      "type": "economy"
    }
  ],
  "timestamp": "2025-02-03T10:00:00.000000Z"
}

Cache this data

This data doesn't change often. Here's how long to cache each type:

Data	Cache Duration	Refresh Strategy
Regions	1 week	On application startup
Localities	1 day	Daily background job
Services	1 day	Daily or on-demand

Example: cache comunas in the browser

// Cache localities in memory or localStorage
const CACHE_KEY = 'nextday_localities'
const CACHE_DURATION = 24 * 60 * 60 * 1000 // 24 hours

async function getLocalities() {
  const cached = localStorage.getItem(CACHE_KEY)

  if (cached) {
    const { data, timestamp } = JSON.parse(cached)
    if (Date.now() - timestamp < CACHE_DURATION) {
      return data
    }
  }

  const response = await fetch('/api/v1/localities', {
    headers: { 'Authorization': `Bearer ${token}` }
  })
  const { data } = await response.json()

  localStorage.setItem(CACHE_KEY, JSON.stringify({
    data,
    timestamp: Date.now()
  }))

  return data
}