Service Areas

Get a service area

Retrieve a specific service area by ID.

Access: an API key with content:service-areas:read (or a master above it: content:service-areas:all, content:all, admin:all) reads the published documents; drafts (aposMode=draft, or a draft _id) need content:service-areas:write (or a master above it). A signed-in person reads as far as their own permissions allow, and anyone else reads the published documents’ public fields.

Rate limit: the key’s own reads-per-minute limit, set when the key is created (default 600); over it, 429 with Retry-After.

GET

service-area

{_id}

cURL

curl --request GET \
  --url https://{host}/api/v1/service-area/{_id} \
  --header 'Authorization: <api-key>'

{
  "title": "",
  "_id": "<string>",
  "type": "<string>",
  "mode": "zips",
  "priority": 0,
  "active": true,
  "zipCodes": "",
  "shapes": [
    {
      "id": "<string>",
      "path": [
        {
          "lat": 0,
          "lng": 0
        }
      ]
    }
  ],
  "slug": "",
  "visibility": "public",
  "scheduledPublish": "<string>",
  "scheduledUnpublish": "<string>",
  "price": 0,
  "priceLabel": "",
  "color": "<string>",
  "description": "",
  "publicNames": [],
  "source": "manual",
  "sourceId": "",
  "archived": false,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "aposShareKey": "k3v9x2m7q1z8w4p6"
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

Authorizations

Authorization

string

header

required

Paste your API key as the CMS showed it: fsk_<site>_<key id>_<secret> (issued under API Keys). ApiKey in front of it works too. Leave it empty to read as the public.

Scopes

content:service-areas:read

Path Parameters

_id

string

required

The document’s _id: a full id names its own locale and mode (the draft’s …:en:draft, the published one’s …:en:published; no aposMode needed), a bare aposDocId takes the request’s (aposLocale, aposMode).

Query Parameters

aposMode

enum<string>

default:published

published (the default) or draft. Drafts need a credential that may see them: an API key with the type’s write scope (content:<type>:write), or a signed-in editor. The public and a key with only the read scope get 403.

Available options:

draft,

published

aposLocale

string

The locale to read or write, e.g. en (default: the site’s default locale).

Example:

"fr"

render-areas

boolean

default:false

true: each area’s widgets come back rendered as HTML (_rendered), beside their data.

Response

Success

ServiceArea content type

title

string

default:""

required

Its title: the name it goes by in every list, and the heading of its page where it has one.

_id

string

required

read-only

The document’s id. On a type with drafts it ends in its locale and mode (…:en:published, …:en:draft): the part before the first colon is its aposDocId, shared by both copies. The {_id} the type’s routes take.

type

string

required

read-only

The document type’s name: always this type’s.

mode

enum<string> | null

default:zips

How is this area defined?

Available options:

zips,

polygon,

null

priority

integer | null

default:0

Sort position — and where areas overlap, the LOWEST number wins the click/search result.

active

boolean | null

default:true

Turn off to keep the area saved but leave it off the map.

zipCodes

string | null

default:""

One or more 5-digit zip codes, separated by commas, spaces or new lines. The map shape is generated automatically from public zip-boundary data.

shapes

Area shape · object[] | null

One or more shapes for this area. Paste coordinates (or draw on the map once a Google Maps key is configured); each shape needs at least 3 points.

Show child attributes

slug

string | null

default:""

The URL name: lowercase words joined by hyphens (letters outside a–z, even emoji, are kept).

visibility

enum<string> | null

default:public

Select whether this content is public or private

Available options:

public,

loginRequired,

null

scheduledPublish

string | null

An ISO 8601 date and time, e.g. 2026-10-21T14:30:00.000Z.

scheduledUnpublish

string | null

An ISO 8601 date and time, e.g. 2026-10-21T14:30:00.000Z.

price

number | null

default:0

The amount shown for this area (0 shows the map section’s “included” label). Use the label below for anything non-standard.

Required range: x >= 0

priceLabel

string | null

default:""

Optional. Shown instead of the formatted price — e.g. “From $40” or “Call for pricing”.

color

string | null

Optional. Leave empty to assign a color from the site palette automatically.

description

string | null

default:""

Optional short text shown when a visitor clicks this area (or finds it via search).

publicNames

Public place names · object[] | null

Optional. The real-world places this area covers — e.g. “Brooklyn” or “Albany County”. Zone names like “Zone A” mean nothing to search engines; these names are what gets published as structured data (with structured data enabled in Site settings → SEO).

Show child attributes

source

enum<string> | null

default:manual

read-only

Set automatically. “Demo placeholder” rows are removed the moment a real service area is published. “Zip feed import” rows were created by Import Zones from Zip Feed and get their zips/price refreshed on re-import.

Available options:

manual,

demo,

zipFeed,

null

sourceId

string | null

default:""

read-only

Internal id of the seed/import that created this row. Empty for manually created areas.

archived

boolean | null

default:false

In the archive: kept, but out of every list and off the site until it is restored. false (or null) for a live document.

createdAt

string<date-time> | null

read-only

When it was created (ISO 8601).

updatedAt

string<date-time> | null

read-only

When it last changed (ISO 8601).

The draft’s preview share key, while its share link is on: the link is the draft’s _url with aposShareKey and aposShareId (the draft’s _id) in its query. Absent otherwise, and on published documents.

Example:

"k3v9x2m7q1z8w4p6"

cURL

curl --request GET \
  --url https://{host}/api/v1/service-area/{_id} \
  --header 'Authorization: <api-key>'

{
  "title": "",
  "_id": "<string>",
  "type": "<string>",
  "mode": "zips",
  "priority": 0,
  "active": true,
  "zipCodes": "",
  "shapes": [
    {
      "id": "<string>",
      "path": [
        {
          "lat": 0,
          "lng": 0
        }
      ]
    }
  ],
  "slug": "",
  "visibility": "public",
  "scheduledPublish": "<string>",
  "scheduledUnpublish": "<string>",
  "price": 0,
  "priceLabel": "",
  "color": "<string>",
  "description": "",
  "publicNames": [],
  "source": "manual",
  "sourceId": "",
  "archived": false,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "aposShareKey": "k3v9x2m7q1z8w4p6"
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

Get started

How the API works

Pages & Site

Content

Media

Forms

Ads & Conversions

Analytics

Signing in (people)

Get a service area

Authorizations

Scopes

Path Parameters

Query Parameters

Response