Clusters & counties
17 endpoints, generated from the API's own OpenAPI document. The organization's county set and its saved clusters of codes or counties.
GET /v2/account/clusters
List the organization's clusters
Credentials: API key or App session. Operation id geoListClusters.
Returns every live (not deleted) cluster of the caller's organization, oldest first, optionally filtered by kind. Clusters are named, reusable sets of NAICS codes, SOC codes or counties, free on every plan and unlimited in number; any member may read them. Reference one on the data endpoints as naics=cluster:<id>, soc=cluster:<id> or areas=cluster:<id> to get one summed series labelled with the cluster's name.
Credential: an API key or a session; any role. Reading is not paused when payment is past due. A sandbox key sees the same organization's clusters as a live key.
Parameters
kindquery · "naics" | "soc" | "fips"- Only clusters of this kind (
naics,socorfips).
Responses
200 success
The organization's live clusters.
As application/json.
dataarray of GeoClusteralways present- The organization's live (not deleted) clusters, oldest first. Not paged.
data[].idstring (uuid)always present- The cluster id; use it as
cluster:<id>on the data endpoints. data[].kind"naics" | "soc" | "fips"always present- What a cluster's members are.
naics: NAICS industry codes (numeric, as the platform stores them), referenced on the data endpoints asnaics=cluster:<id>.soc: SOC occupation codes, referenced assoc=cluster:<id>.fips: 5-digit county FIPS codes, referenced asareas=cluster:<id>(an area cluster). Fixed when the cluster is created and never changes. data[].namestringalways present- The name, trimmed of surrounding spaces, 1 to 120 characters. (at most 120 characters)
data[].codesarray of stringalways present- The members as saved: duplicates removed.
fipsclusters are sorted by FIPS;naicsandsocclusters are in the taxonomy's own display order. NAICS codes are returned as strings of digits. data[].created_atstring (date-time)always present- When the cluster was created.
data[].updated_atstring (date-time)always present- When the cluster was last renamed, re-membered or restored.
400 error
Bad Request. Codes: kind_invalid (kind is not naics, soc or fips), bad_request (kind given more than once).
As application/problem+json.
401 error
Unauthorized. Codes: unauthenticated (no valid API key or session); key_revoked (an API key that was revoked: revoked_at, and reason -- holder, admin, member_removed, seat_removed, api_disabled, addon_ended, account_closed, org_closed, retired, or null for a key revoked before T110 -- and a sentence saying when and why).
As application/problem+json.
403 error
Forbidden. Codes: no_membership, account_suspended, org_suspended, org_closed, wrong_instance (a key of the mode this process does not serve; base_url names the address that serves it).
As application/problem+json.
404 error
Not Found. Codes: not_found (the X-DTG-Org header names no organization the caller may use).
As application/problem+json.
429 error
rate_limited (the per-minute ceiling, X-RateLimit-* say which), points_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server_busy or sandbox_busy (load; retry after Retry-After). A refused server_busy request is not metered.
As application/problem+json.
Retry-Afterheader- Seconds to wait before retrying.
X-RateLimit-Limitheader- The per-minute request ceiling that applies.
X-RateLimit-Remainingheader- Requests left in the current window.
X-RateLimit-Resetheader- Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as
Retry-After).
Problem codes: kind_invalid (400), bad_request (400), unauthenticated (401), key_revoked (401), account_closed (401), org_closed (401), no_membership (403), account_suspended (403), org_suspended (403), org_closed (403), wrong_instance (403), not_found (404). Every problem is a problem document.
POST /v2/account/clusters
Create a cluster
Credentials: API key or App session. Operation id geoCreateCluster.
Saves a named set of NAICS codes, SOC codes or counties. Validation happens here, at save: NAICS and SOC members must exist in the current vintage's taxonomy and may not include an ancestor and a descendant of each other (so the cluster can always be summed); county (fips) members must lie inside the organization's active entitled county set. Names are unique per organization and kind among live clusters (case-insensitively), and so are member sets (order-independent), L10; a NAICS "Healthcare" and a SOC "Healthcare" can coexist. Clusters are free on every plan.
Credential: an API key or a session; any role may create. While the organization's payment is past due, creating is refused 403 plan_required with entitlement: "past_due". A sandbox key may create clusters and use them against sandbox geography: it is never past due, and every 5-digit county code passes the entitlement check (the sandbox's synthetic counties included). Side effect: one audit row, cluster.created.
Request body
Required; application/json.
kind"naics" | "soc" | "fips"required- What a cluster's members are.
naics: NAICS industry codes (numeric, as the platform stores them), referenced on the data endpoints asnaics=cluster:<id>.soc: SOC occupation codes, referenced assoc=cluster:<id>.fips: 5-digit county FIPS codes, referenced asareas=cluster:<id>(an area cluster). Fixed when the cluster is created and never changes. namestringrequired- The cluster's name, 1 to 120 characters after trimming. Unique per organization and kind among live clusters, case-insensitively. (at most 120 characters)
codesarray of stringrequired- The members, 1 to 1,000 strings (duplicates are dropped).
naics: numeric NAICS codes known to the current vintage's taxonomy, with no code that is an ancestor or descendant of another (so the cluster can always be summed).soc: SOC codes known to the current vintage's taxonomy, with the same no-overlap rule.fips: 5-digit county FIPS codes, every one inside the organization's ACTIVE entitled county set (the counties fromGET /v2/account/countiesthat are not shed, plus the trial county while a trial runs; every 5-digit code passes for an organization entitled to every county, and for a sandbox key).
Responses
201 success
The created cluster.
As application/json.
idstring (uuid)always present- The cluster id; use it as
cluster:<id>on the data endpoints. kind"naics" | "soc" | "fips"always present- What a cluster's members are.
naics: NAICS industry codes (numeric, as the platform stores them), referenced on the data endpoints asnaics=cluster:<id>.soc: SOC occupation codes, referenced assoc=cluster:<id>.fips: 5-digit county FIPS codes, referenced asareas=cluster:<id>(an area cluster). Fixed when the cluster is created and never changes. namestringalways present- The name, trimmed of surrounding spaces, 1 to 120 characters. (at most 120 characters)
codesarray of stringalways present- The members as saved: duplicates removed.
fipsclusters are sorted by FIPS;naicsandsocclusters are in the taxonomy's own display order. NAICS codes are returned as strings of digits. created_atstring (date-time)always present- When the cluster was created.
updated_atstring (date-time)always present- When the cluster was last renamed, re-membered or restored.
400 error
Bad Request. Codes: kind_invalid (kind missing or not naics, soc or fips), name_invalid (name missing, blank, or over 120 characters), codes_invalid (codes not a non-empty array of strings), member_cap (more than 1,000 codes), bad_code (a county that is not 5 digits, or a NAICS code that is not numeric; errors names it), unknown_codes (codes the current taxonomy does not know; errors names them), codes_overlap (one code contains another; errors names the pair as {code, contained_in}), counties_outside_set (counties outside the organization's active entitled set; errors lists each {fips}), malformed_json (the body is not JSON).
As application/problem+json.
401 error
Unauthorized. Codes: unauthenticated (no valid API key or session); key_revoked (an API key that was revoked: revoked_at, and reason -- holder, admin, member_removed, seat_removed, api_disabled, addon_ended, account_closed, org_closed, retired, or null for a key revoked before T110 -- and a sentence saying when and why).
As application/problem+json.
403 error
Forbidden. Codes: plan_required with entitlement: "past_due" (payment is past due; cluster editing is paused until the balance is settled, L18), no_membership, account_suspended, org_suspended, org_closed, wrong_instance (base_url names the address that serves the key).
As application/problem+json.
404 error
Not Found. Codes: not_found (the X-DTG-Org header names no organization the caller may use).
As application/problem+json.
409 error
Conflict. Codes: cluster_name_taken (a live cluster of this kind already has this name), cluster_members_taken (a live cluster of this kind already has exactly these members). Both carry existing, the cluster that holds it.
As application/problem+json.
413 error
Payload Too Large. Codes: body_too_large (the body is over 64 KiB; carries limit_bytes).
As application/problem+json.
429 error
rate_limited (the per-minute ceiling, X-RateLimit-* say which), points_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server_busy or sandbox_busy (load; retry after Retry-After). A refused server_busy request is not metered.
As application/problem+json.
Retry-Afterheader- Seconds to wait before retrying.
X-RateLimit-Limitheader- The per-minute request ceiling that applies.
X-RateLimit-Remainingheader- Requests left in the current window.
X-RateLimit-Resetheader- Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as
Retry-After).
Problem codes: kind_invalid (400), name_invalid (400), codes_invalid (400), member_cap (400), bad_code (400), unknown_codes (400), codes_overlap (400), counties_outside_set (400), malformed_json (400), unauthenticated (401), key_revoked (401), account_closed (401), org_closed (401), plan_required (403), no_membership (403), account_suspended (403), org_suspended (403), org_closed (403), wrong_instance (403), not_found (404), cluster_name_taken (409), cluster_members_taken (409), body_too_large (413). Every problem is a problem document.
GET /v2/account/clusters/deleted
List deleted clusters that can still be restored or are awaiting purge
Credentials: API key or App session. Operation id geoListDeletedClusters.
Returns the organization's soft-deleted clusters, most recently deleted first, each with who deleted it, when, and its restore deadline (restorable_until). A deleted cluster can be restored for 30 days by default (D70, cluster_restore_days on GET /v2/account); after that the nightly purge deletes it for good and it leaves this list.
Credential: an API key or a session; owner or admin only.
Parameters
kindquery · "naics" | "soc" | "fips"- Only deleted clusters of this kind (
naics,socorfips).
Responses
200 success
The deleted clusters.
As application/json.
dataarray of GeoDeletedClusteralways present- The organization's soft-deleted clusters that the nightly purge has not yet removed, most recently deleted first. Not paged.
data[].idstring (uuid)always present- The cluster id; use it as
cluster:<id>on the data endpoints. data[].kind"naics" | "soc" | "fips"always present- What a cluster's members are.
naics: NAICS industry codes (numeric, as the platform stores them), referenced on the data endpoints asnaics=cluster:<id>.soc: SOC occupation codes, referenced assoc=cluster:<id>.fips: 5-digit county FIPS codes, referenced asareas=cluster:<id>(an area cluster). Fixed when the cluster is created and never changes. data[].namestringalways present- The name, trimmed of surrounding spaces, 1 to 120 characters. (at most 120 characters)
data[].codesarray of stringalways present- The members as saved: duplicates removed.
fipsclusters are sorted by FIPS;naicsandsocclusters are in the taxonomy's own display order. NAICS codes are returned as strings of digits. data[].created_atstring (date-time)always present- When the cluster was created.
data[].updated_atstring (date-time)always present- When the cluster was last renamed, re-membered or restored.
data[].deleted_atstring (date-time)always present- When the cluster was deleted.
data[].deleted_byGeoActor or nullalways present- Who deleted it; null when the deleting account is no longer on record.
data[].deleted_by.idstring (uuid)- The account id.
data[].deleted_by.emailstring or null- The account's email address; null when the account no longer carries one.
data[].deleted_by.display_namestring or null- The account's display name; null when none was set.
data[].restorablebooleanalways present- True while the restore window is open (
restorable_untilis in the future). This list is owner/admin only, so the role half of the rule always holds here. data[].restorable_untilstring (date-time)always present- The restore deadline:
deleted_atplus the organization's restore window (30 days by default, D70;GET /v2/accountreports it ascluster_restore_days). Always present. A value in the past means the window has closed; the nightly purge then deletes the cluster for good, after which it no longer appears here and any reference to it answerscluster_not_found.
400 error
Bad Request. Codes: kind_invalid (kind is not naics, soc or fips), bad_request (kind given more than once).
As application/problem+json.
401 error
Unauthorized. Codes: unauthenticated (no valid API key or session); key_revoked (an API key that was revoked: revoked_at, and reason -- holder, admin, member_removed, seat_removed, api_disabled, addon_ended, account_closed, org_closed, retired, or null for a key revoked before T110 -- and a sentence saying when and why).
As application/problem+json.
403 error
Forbidden. Codes: role_required (the caller is a member, not an owner or admin; carries required), no_membership, account_suspended, org_suspended, org_closed, wrong_instance (base_url names the address that serves the key).
As application/problem+json.
404 error
Not Found. Codes: not_found (the X-DTG-Org header names no organization the caller may use).
As application/problem+json.
429 error
rate_limited (the per-minute ceiling, X-RateLimit-* say which), points_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server_busy or sandbox_busy (load; retry after Retry-After). A refused server_busy request is not metered.
As application/problem+json.
Retry-Afterheader- Seconds to wait before retrying.
X-RateLimit-Limitheader- The per-minute request ceiling that applies.
X-RateLimit-Remainingheader- Requests left in the current window.
X-RateLimit-Resetheader- Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as
Retry-After).
Problem codes: kind_invalid (400), bad_request (400), unauthenticated (401), key_revoked (401), account_closed (401), org_closed (401), role_required (403), no_membership (403), account_suspended (403), org_suspended (403), org_closed (403), wrong_instance (403), not_found (404). Every problem is a problem document.
GET /v2/account/clusters/{id}
Get one cluster
Credentials: API key or App session. Operation id geoGetCluster.
Returns one of the organization's live clusters. A cluster this organization deleted (and the purge has not yet removed) answers 404 cluster_deleted with its name, who deleted it, when, whether this caller may restore it, and the restore deadline. Anything else (never existed, another organization's, purged, malformed id) answers 404 cluster_not_found.
Credential: an API key or a session; any role.
Parameters
idpath · string (uuid)required- The cluster id.
Responses
200 success
The cluster.
As application/json.
idstring (uuid)always present- The cluster id; use it as
cluster:<id>on the data endpoints. kind"naics" | "soc" | "fips"always present- What a cluster's members are.
naics: NAICS industry codes (numeric, as the platform stores them), referenced on the data endpoints asnaics=cluster:<id>.soc: SOC occupation codes, referenced assoc=cluster:<id>.fips: 5-digit county FIPS codes, referenced asareas=cluster:<id>(an area cluster). Fixed when the cluster is created and never changes. namestringalways present- The name, trimmed of surrounding spaces, 1 to 120 characters. (at most 120 characters)
codesarray of stringalways present- The members as saved: duplicates removed.
fipsclusters are sorted by FIPS;naicsandsocclusters are in the taxonomy's own display order. NAICS codes are returned as strings of digits. created_atstring (date-time)always present- When the cluster was created.
updated_atstring (date-time)always present- When the cluster was last renamed, re-membered or restored.
401 error
Unauthorized. Codes: unauthenticated (no valid API key or session); key_revoked (an API key that was revoked: revoked_at, and reason -- holder, admin, member_removed, seat_removed, api_disabled, addon_ended, account_closed, org_closed, retired, or null for a key revoked before T110 -- and a sentence saying when and why).
As application/problem+json.
403 error
Forbidden. Codes: no_membership, account_suspended, org_suspended, org_closed, wrong_instance (base_url names the address that serves the key).
As application/problem+json.
404 error
Not Found. Codes: cluster_not_found (no such cluster for this organization), cluster_deleted (deleted by this organization; carries cluster, restorable, restorable_until), not_found (the X-DTG-Org header names no organization the caller may use).
As application/problem+json.
429 error
rate_limited (the per-minute ceiling, X-RateLimit-* say which), points_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server_busy or sandbox_busy (load; retry after Retry-After). A refused server_busy request is not metered.
As application/problem+json.
Retry-Afterheader- Seconds to wait before retrying.
X-RateLimit-Limitheader- The per-minute request ceiling that applies.
X-RateLimit-Remainingheader- Requests left in the current window.
X-RateLimit-Resetheader- Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as
Retry-After).
Problem codes: unauthenticated (401), key_revoked (401), account_closed (401), org_closed (401), no_membership (403), account_suspended (403), org_suspended (403), org_closed (403), wrong_instance (403), cluster_not_found (404), cluster_deleted (404), not_found (404). Every problem is a problem document.
PUT /v2/account/clusters/{id}
Rename or re-member a cluster
Credentials: API key or App session. Operation id geoUpdateCluster.
Changes a cluster's name, its members, or both; a property left out keeps its value. kind cannot change (create a new cluster instead). New members are validated exactly as on create, and the name and member-set uniqueness rules apply, so a rename or re-member can answer 409.
Credential: an API key or a session; any role. While payment is past due this is refused 403 plan_required with entitlement: "past_due"; a sandbox key is never past due. Side effect: one audit row, cluster.updated.
Parameters
idpath · string (uuid)required- The cluster id.
Request body
Required; application/json.
kind"naics" | "soc" | "fips"- Optional. May be sent only if it equals the cluster's current kind; a different kind is refused 400
kind_immutable. namestring- The new name, 1 to 120 characters after trimming. Unique per organization and kind among live clusters, case-insensitively. (at most 120 characters)
codesarray of string- The new member list, validated exactly as on create (see
GeoClusterCreate.codes) and replacing the old one whole.
Responses
200 success
The updated cluster.
As application/json.
idstring (uuid)always present- The cluster id; use it as
cluster:<id>on the data endpoints. kind"naics" | "soc" | "fips"always present- What a cluster's members are.
naics: NAICS industry codes (numeric, as the platform stores them), referenced on the data endpoints asnaics=cluster:<id>.soc: SOC occupation codes, referenced assoc=cluster:<id>.fips: 5-digit county FIPS codes, referenced asareas=cluster:<id>(an area cluster). Fixed when the cluster is created and never changes. namestringalways present- The name, trimmed of surrounding spaces, 1 to 120 characters. (at most 120 characters)
codesarray of stringalways present- The members as saved: duplicates removed.
fipsclusters are sorted by FIPS;naicsandsocclusters are in the taxonomy's own display order. NAICS codes are returned as strings of digits. created_atstring (date-time)always present- When the cluster was created.
updated_atstring (date-time)always present- When the cluster was last renamed, re-membered or restored.
400 error
Bad Request. Codes: kind_immutable (a kind different from the cluster's), name_invalid (blank, or over 120 characters), codes_invalid, member_cap, bad_code, unknown_codes, codes_overlap, counties_outside_set (as on create; errors names the offending members), malformed_json (the body is not JSON).
As application/problem+json.
401 error
Unauthorized. Codes: unauthenticated (no valid API key or session); key_revoked (an API key that was revoked: revoked_at, and reason -- holder, admin, member_removed, seat_removed, api_disabled, addon_ended, account_closed, org_closed, retired, or null for a key revoked before T110 -- and a sentence saying when and why).
As application/problem+json.
403 error
Forbidden. Codes: plan_required with entitlement: "past_due" (payment is past due; cluster editing is paused, L18), no_membership, account_suspended, org_suspended, org_closed, wrong_instance (base_url names the address that serves the key).
As application/problem+json.
404 error
Not Found. Codes: cluster_not_found (no such cluster for this organization), cluster_deleted (deleted by this organization; restore it first), not_found (the X-DTG-Org header names no organization the caller may use).
As application/problem+json.
409 error
Conflict. Codes: cluster_name_taken (another live cluster of this kind has this name), cluster_members_taken (another live cluster of this kind has exactly these members). Both carry existing.
As application/problem+json.
413 error
Payload Too Large. Codes: body_too_large (the body is over 64 KiB; carries limit_bytes).
As application/problem+json.
429 error
rate_limited (the per-minute ceiling, X-RateLimit-* say which), points_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server_busy or sandbox_busy (load; retry after Retry-After). A refused server_busy request is not metered.
As application/problem+json.
Retry-Afterheader- Seconds to wait before retrying.
X-RateLimit-Limitheader- The per-minute request ceiling that applies.
X-RateLimit-Remainingheader- Requests left in the current window.
X-RateLimit-Resetheader- Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as
Retry-After).
Problem codes: kind_immutable (400), name_invalid (400), codes_invalid (400), member_cap (400), bad_code (400), unknown_codes (400), codes_overlap (400), counties_outside_set (400), malformed_json (400), unauthenticated (401), key_revoked (401), account_closed (401), org_closed (401), plan_required (403), no_membership (403), account_suspended (403), org_suspended (403), org_closed (403), wrong_instance (403), cluster_not_found (404), cluster_deleted (404), not_found (404), cluster_name_taken (409), cluster_members_taken (409), body_too_large (413). Every problem is a problem document.
DELETE /v2/account/clusters/{id}
Delete a cluster (restorable)
Credentials: API key or App session. Operation id geoDeleteCluster.
Soft-deletes a cluster. It disappears from the list, and every reference to it (this path and cluster:<id> on the data endpoints) answers 404 cluster_deleted. An owner or admin can restore it with POST /v2/account/clusters/{id}/restore until restorable_until (30 days by default, D70); the nightly purge then deletes it for good.
Credential: an API key or a session; any role may delete. Not paused when payment is past due. Side effect: one audit row, cluster.deleted, recording who deleted it.
Parameters
idpath · string (uuid)required- The cluster id.
Responses
204 success
Deleted.
401 error
Unauthorized. Codes: unauthenticated (no valid API key or session); key_revoked (an API key that was revoked: revoked_at, and reason -- holder, admin, member_removed, seat_removed, api_disabled, addon_ended, account_closed, org_closed, retired, or null for a key revoked before T110 -- and a sentence saying when and why).
As application/problem+json.
403 error
Forbidden. Codes: no_membership, account_suspended, org_suspended, org_closed, wrong_instance (base_url names the address that serves the key).
As application/problem+json.
404 error
Not Found. Codes: cluster_not_found (no such cluster for this organization), cluster_deleted (already deleted), not_found (the X-DTG-Org header names no organization the caller may use).
As application/problem+json.
429 error
rate_limited (the per-minute ceiling, X-RateLimit-* say which), points_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server_busy or sandbox_busy (load; retry after Retry-After). A refused server_busy request is not metered.
As application/problem+json.
Retry-Afterheader- Seconds to wait before retrying.
X-RateLimit-Limitheader- The per-minute request ceiling that applies.
X-RateLimit-Remainingheader- Requests left in the current window.
X-RateLimit-Resetheader- Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as
Retry-After).
Problem codes: unauthenticated (401), key_revoked (401), account_closed (401), org_closed (401), no_membership (403), account_suspended (403), org_suspended (403), org_closed (403), wrong_instance (403), cluster_not_found (404), cluster_deleted (404), not_found (404). Every problem is a problem document.
POST /v2/account/clusters/{id}/restore
Restore a deleted cluster
Credentials: API key or App session. Operation id geoRestoreCluster.
Puts a soft-deleted cluster back while its restore window is open (until restorable_until, 30 days after deletion by default, D70). Idempotent: restoring a cluster that is already live returns it unchanged with 200. Past the window the answer is 404 cluster_deleted with restorable: false and a restorable_until in the past; after the purge it is cluster_not_found. A name or member set taken by another cluster since the deletion answers 409. No request body.
Credential: an API key or a session; owner or admin only. While payment is past due this is refused 403 plan_required with entitlement: "past_due". Side effect: one audit row, cluster.restored.
Parameters
idpath · string (uuid)required- The id of the deleted cluster.
Responses
200 success
The restored (or already live) cluster.
As application/json.
idstring (uuid)always present- The cluster id; use it as
cluster:<id>on the data endpoints. kind"naics" | "soc" | "fips"always present- What a cluster's members are.
naics: NAICS industry codes (numeric, as the platform stores them), referenced on the data endpoints asnaics=cluster:<id>.soc: SOC occupation codes, referenced assoc=cluster:<id>.fips: 5-digit county FIPS codes, referenced asareas=cluster:<id>(an area cluster). Fixed when the cluster is created and never changes. namestringalways present- The name, trimmed of surrounding spaces, 1 to 120 characters. (at most 120 characters)
codesarray of stringalways present- The members as saved: duplicates removed.
fipsclusters are sorted by FIPS;naicsandsocclusters are in the taxonomy's own display order. NAICS codes are returned as strings of digits. created_atstring (date-time)always present- When the cluster was created.
updated_atstring (date-time)always present- When the cluster was last renamed, re-membered or restored.
401 error
Unauthorized. Codes: unauthenticated (no valid API key or session); key_revoked (an API key that was revoked: revoked_at, and reason -- holder, admin, member_removed, seat_removed, api_disabled, addon_ended, account_closed, org_closed, retired, or null for a key revoked before T110 -- and a sentence saying when and why).
As application/problem+json.
403 error
Forbidden. Codes: role_required (owner or admin only; carries required), plan_required with entitlement: "past_due" (payment is past due; cluster editing is paused, L18), no_membership, account_suspended, org_suspended, org_closed, wrong_instance (base_url names the address that serves the key).
As application/problem+json.
404 error
Not Found. Codes: cluster_not_found (no such cluster for this organization, or already purged), cluster_deleted (the restore window has closed; restorable is false and restorable_until is in the past), not_found (the X-DTG-Org header names no organization the caller may use).
As application/problem+json.
409 error
Conflict. Codes: cluster_name_taken (a live cluster of this kind took the name since the deletion), cluster_members_taken (a live cluster of this kind took the member set since the deletion). Both carry existing.
As application/problem+json.
429 error
rate_limited (the per-minute ceiling, X-RateLimit-* say which), points_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server_busy or sandbox_busy (load; retry after Retry-After). A refused server_busy request is not metered.
As application/problem+json.
Retry-Afterheader- Seconds to wait before retrying.
X-RateLimit-Limitheader- The per-minute request ceiling that applies.
X-RateLimit-Remainingheader- Requests left in the current window.
X-RateLimit-Resetheader- Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as
Retry-After).
Problem codes: unauthenticated (401), key_revoked (401), account_closed (401), org_closed (401), role_required (403), plan_required (403), no_membership (403), account_suspended (403), org_suspended (403), org_closed (403), wrong_instance (403), cluster_not_found (404), cluster_deleted (404), not_found (404), cluster_name_taken (409), cluster_members_taken (409). Every problem is a problem document.
GET /v2/account/counties
The organization's county set
Credentials: API key or App session. Operation id geoGetCounties.
Returns the organization's county set (D44: a plan buys counties) with its capacity, how many are active and leaving, the change window when scheduled removals land, the latest pending removal batch, and whether a free keep-which-counties choice is owed after an involuntary shrink. Each county carries its source (manual, state, msa, trial), is_catchall, shed and remove_effective_at.
Credential: an API key or a session; any role may read (edit_roles says who may change it). A sandbox key reads the organization's real county set; the sandbox's own geography is not a county set (every sandbox area is entitled).
Responses
200 success
The county set.
As application/json.
counties_includedintegeralways present- The counties the plan includes; -1 means every county.
counties_purchasedintegeralways present- Paid county slots bought beyond the plan's included counties.
capacityinteger or "all"always present- How many counties may be active at once (
counties_included+counties_purchased), or the stringall. active_countintegeralways present- Counties in the set that are not shed and not the trial county, including those scheduled to leave.
leaving_countintegeralways present- Of
active_count, those with a scheduled removal. They stay entitled until the change window date but no longer hold a slot. count_after_pendingintegeralways presentactive_countminusleaving_count: the count that is measured against capacity now and after the pending batches land.universeintegeralways present- The number of counties that exist to choose from (3,194, including the 50 state catch-alls).
county_price_usd_monthnumber or nullalways present- The monthly price in US dollars of one county slot beyond the plan's included counties; null when the plan does not sell extra counties. Prices are canonical in
GET /v2/plans. change_windowobjectalways present- When scheduled removals take effect.
change_window.anchor_dayinteger or nullalways present- The organization's monthly subscription anchor day; null when unknown (the 1st is then used). (1 to 31)
change_window.next_effective_atstring (date-time)always present- The next anchor date (midnight UTC); a removal scheduled now takes effect then. Days 29 to 31 fall on a shorter month's last day.
pending_changeGeoCountyChange or nullalways present- The most recently scheduled pending removal batch, or null when none is pending. Older pending batches, if any, still apply; their counties show
remove_effective_at. pending_change.idstring (uuid)- The batch id; cancel it with
DELETE /v2/account/counties/changes/{id}. pending_change.requested_atstring (date-time)- When the batch was scheduled.
pending_change.effective_atstring (date-time)- When the counties leave the set (the organization's next subscription anchor date at the time it was scheduled).
pending_change.additionsarray of string- Reserved; always empty today, because additions are immediate.
pending_change.removalsarray of string- The 5-digit FIPS codes that leave on
effective_at. pending_change.paid_slots_deltainteger- The change to the paid county count the batch carries; 0 unless
release_slotswas sent, negative when it gives slots back. pending_change.status"pending" | "applied" | "cancelled"- Always
pendingwhere this object is returned. county_choice_pendingbooleanalways present- True after an involuntary shrink (a downgrade or dunning) shed counties; an owner or admin should choose which to keep with
POST /v2/account/counties/confirm, and that choice is free. edit_rolesarray of stringalways present- The roles that may change the set (
["owner", "admin"]). dataarray of GeoCountyalways present- Every county in the set that has not been removed (shed and leaving ones included), ordered by FIPS.
data[].fipsstringalways present- The 5-digit county FIPS code.
data[].namestring or nullalways present- The county's name in the current vintage; null if the current vintage does not carry this code.
data[].statestringalways present- The 2-digit state FIPS code (the first two digits of
fips). data[].source"manual" | "state" | "msa" | "trial"always present- How a county joined the set.
manual: named directly, or arrived in a mixed batch.state: the whole batch came from onestate:XXshortcut.msa: the whole batch came from onemsa:NNNNNshortcut.trial: the trial county, managed by the trial; it never counts against capacity and cannot be removed here. data[].is_catchallbooleanalways present- True for a state's "Unknown Or Undefined" catch-all (a FIPS ending in 999, O34). It carries the employment QCEW could not place in a named county. It is a purchasable county like any other and counts toward capacity; the flag only drives presentation (an
msa:shortcut and/mapnever include one). data[].shedbooleanalways present- True when a downgrade composite read-locked the county because the set outgrew capacity (D20/D44). A shed county is kept, not removed, does not count toward capacity and is not entitled; an upgrade, or adding it again, restores it.
data[].added_atstring (date-time)always present- When the county joined the set.
data[].remove_effective_atstring (date-time) or nullalways present- When a scheduled removal takes the county out of the set (the change window date), or null when none is scheduled. Until then it stays entitled, but it no longer holds a slot, so a replacement can take its place at no cost (D41 rider).
401 error
Unauthorized. Codes: unauthenticated (no valid API key or session); key_revoked (an API key that was revoked: revoked_at, and reason -- holder, admin, member_removed, seat_removed, api_disabled, addon_ended, account_closed, org_closed, retired, or null for a key revoked before T110 -- and a sentence saying when and why).
As application/problem+json.
403 error
Forbidden. Codes: no_membership, account_suspended, org_suspended, org_closed, wrong_instance (base_url names the address that serves the key).
As application/problem+json.
404 error
Not Found. Codes: not_found (the X-DTG-Org header names no organization the caller may use).
As application/problem+json.
429 error
rate_limited (the per-minute ceiling, X-RateLimit-* say which), points_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server_busy or sandbox_busy (load; retry after Retry-After). A refused server_busy request is not metered.
As application/problem+json.
Retry-Afterheader- Seconds to wait before retrying.
X-RateLimit-Limitheader- The per-minute request ceiling that applies.
X-RateLimit-Remainingheader- Requests left in the current window.
X-RateLimit-Resetheader- Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as
Retry-After).
Problem codes: unauthenticated (401), key_revoked (401), account_closed (401), org_closed (401), no_membership (403), account_suspended (403), org_suspended (403), org_closed (403), wrong_instance (403), not_found (404). Every problem is a problem document.
POST /v2/account/counties
Add counties (immediate)
Credentials: API key or App session. Operation id geoAddCounties.
Adds counties to the set at once. Entries may be 5-digit FIPS codes or shortcuts expanded against the current vintage: state:XX (the state's counties, catch-all included, O34) and msa:NNNNN (the MSA's counties at the latest map, never a catch-all). A shed county named again is restored. Counties already present are reported and left as they are.
Counties scheduled to leave no longer hold a slot, so swapping one county for another costs nothing (D41 rider). When the addition would exceed capacity and the plan sells extra counties, the first call is refused 409 confirm_purchase_required with a preview (interval-aware: what is charged now for the rest of the period, and what at each renewal); re-send with confirm_purchase: true to buy the slots. The slot increase is prorated and charged to the card immediately; the counties are granted even if the card declines, and the 201's payment says which happened. A 201 is not proof the money moved.
Credential: an API key or a session; owner or admin only. Side effects: may change the subscription's county quantity and charge the card; one audit row, counties.added.
Request body
Required; application/json.
addarray of stringrequired- 1 to 200 entries, each one of: a 5-digit county FIPS code;
state:XX(every county of that state in the current vintage, its catch-all included, O34);msa:NNNNN(the MSA's member counties at the latest map, never a catch-all). Shortcuts expand on the server; duplicates collapse. confirm_purchaseboolean- Send
trueto buy the extra county slots when the addition goes over capacity. Without it an over-capacity addition is refused 409confirm_purchase_requiredwith thepreview. The slot increase is prorated to the rest of the billing period and charged to the card at once.
Responses
201 success
Added (and, when slots were bought, the purchase and the charge's outcome).
As application/json.
addedarray of stringalways present- The 5-digit FIPS codes newly added to the set.
restoredarray of stringalways present- Shed counties named again and therefore made active again.
already_presentarray of stringalways present- Counties that were already active and were left as they were (a county with a scheduled removal stays scheduled; cancel the batch to keep it).
expandedarray of objectalways present- One entry per
state:ormsa:shortcut, in request order. expanded[].selectorstringalways present- The shortcut as sent (trimmed).
expanded[].countiesintegeralways present- How many counties it expanded to.
counties_purchasedintegeralways present- The paid county slot count after the request.
capacityinteger or "all"always present- The capacity after the request, or
all. active_countintegeralways present- The counted total after the request (not shed, not the trial county, not scheduled to leave).
purchaseGeoPurchasePreview or nullalways present- The purchase that was made, or null when the addition fitted capacity.
purchase.counties_afterinteger- The counted county total after this addition.
purchase.over_planinteger- How many of those exceed the plan's included counties.
purchase.slots_requiredinteger- The paid county slot count this purchase sets (equal to
over_plan). purchase.interval"month" | "year"- The organization's billing interval.
purchase.county_price_usdnumber- The price of one slot per billing interval (an annual price on a yearly plan).
purchase.recurring_delta_usdnumber- What the slots over the plan cost at each renewal, per interval.
purchase.prorated_charge_usdnumber- What is charged now for the rest of the current period. Falls back to
recurring_delta_usdwhen there is no subscription to price against. purchase.proration"prorated"- Always
prorated. An increase applies at once and is prorated. purchase.summarystring- One plain-English sentence, such as "56 counties, 41 over your plan, $X/mo more".
purchase.commitmentstring- Plain-English terms - what is charged now, what at each renewal, and that the count can be reduced at renewal while which counties are covered can change monthly at no cost.
paymentGeoCountyPayment or nullalways present- The charge's outcome when slots were bought, or null. A 201 with
payment.statusfailedmeans the counties are granted and the charge was not. payment.status"paid" | "failed"failedwhen the card was declined (the subscription is now past due).payment.attempted_usdnumber- The amount charged or attempted, in US dollars.
payment.subscription_statusstring or null- The subscription's status after the charge (for example
activeorpast_due); null when there is none. payment.past_due_sincestring (date-time) or null- When the subscription became past due; null when it is not.
payment.invoiceobject or null- The latest invoice when it is unpaid, so the customer can be pointed at it; null when it was paid.
payment.invoice.idstring- The invoice id.
payment.invoice.numberstring or null- The invoice number, when one has been assigned.
payment.invoice.statusstring- The invoice status (for example
open). payment.invoice.amount_due_centsinteger- The amount due, in US cents.
payment.invoice.hosted_invoice_urlstring (uri) or null- The page where the invoice can be paid, when there is one.
payment.detailstring- One plain-English sentence describing the outcome.
400 error
Bad Request. Codes: bad_request (add missing, empty, over 200 entries, a non-string entry, an entry that is not a 5-digit FIPS, state:XX or msa:NNNNN, or an unknown state, MSA or county), retired_msa (an MSA the current map no longer defines; carries msa, retired_after, successors), malformed_json (the body is not JSON).
As application/problem+json.
401 error
Unauthorized. Codes: unauthenticated (no valid API key or session); key_revoked (an API key that was revoked: revoked_at, and reason -- holder, admin, member_removed, seat_removed, api_disabled, addon_ended, account_closed, org_closed, retired, or null for a key revoked before T110 -- and a sentence saying when and why).
As application/problem+json.
403 error
Forbidden. Codes: role_required (owner or admin only; carries required), plan_required with entitlement: "counties_included" (the plan includes no counties, or the addition exceeds the plan's counties and the plan does not sell more), contract_managed (an invoiced organization over capacity: contact Data Tactical Group; carries preview), no_membership, account_suspended, org_suspended, org_closed, wrong_instance (base_url names the address that serves the key). A sandbox key: sandbox_read_only (it may write only clusters).
As application/problem+json.
404 error
Not Found. Codes: not_found (the X-DTG-Org header names no organization the caller may use).
As application/problem+json.
409 error
Conflict. Codes: confirm_purchase_required (over capacity; carries preview; re-send with confirm_purchase: true), billing_in_progress (another billing change for this organization is running; retry), not_subscribed (there is no active subscription to add county slots to).
As application/problem+json.
413 error
Payload Too Large. Codes: body_too_large (the body is over 256 KiB; carries limit_bytes).
As application/problem+json.
429 error
rate_limited (the per-minute ceiling, X-RateLimit-* say which), points_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server_busy or sandbox_busy (load; retry after Retry-After). A refused server_busy request is not metered.
As application/problem+json.
Retry-Afterheader- Seconds to wait before retrying.
X-RateLimit-Limitheader- The per-minute request ceiling that applies.
X-RateLimit-Remainingheader- Requests left in the current window.
X-RateLimit-Resetheader- Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as
Retry-After).
Problem codes: bad_request (400), retired_msa (400), malformed_json (400), unauthenticated (401), key_revoked (401), account_closed (401), org_closed (401), role_required (403), plan_required (403), contract_managed (403), no_membership (403), account_suspended (403), org_suspended (403), org_closed (403), wrong_instance (403), sandbox_read_only (403), not_found (404), confirm_purchase_required (409), billing_in_progress (409), not_subscribed (409), body_too_large (413). Every problem is a problem document.
POST /v2/account/counties/remove
Schedule a removal batch for the next anchor date
Credentials: API key or App session. Operation id geoRemoveCounties.
Schedules the named counties to leave the set on the organization's next monthly subscription anchor date (effective_at); until then they stay entitled. The batch frees their slots at once, so a replacement can be added immediately at no cost (D41 rider). It does NOT change the paid county count: slots_releasable reports how many slots are now spare, and release_slots: true also gives them back (at period end, not credited). The trial county is refused (listed in refused); counties not in the set are ignored. Cancel with DELETE /v2/account/counties/changes/{id}. When the batch lands, owners and admins are notified (county_batch_applied).
Credential: an API key or a session; owner or admin only. Side effect: one audit row, counties.removal_scheduled.
Request body
Required; application/json.
removearray of stringrequired- 1 to 200 counties to remove, in the same forms as
add(5-digit FIPS,state:XX,msa:NNNNN). Counties not in the set are ignored; the trial county is refused. release_slotsboolean- Default false: the paid county count is left alone (a set change is not a count change, D41 rider) and
slots_releasablereports what could be given back. True also lowers the paid count by that many slots, at period end, not credited, usable until then. (default false)
Responses
202 success
The batch was scheduled.
As application/json.
idstring (uuid)always present- The batch id; cancel with
DELETE /v2/account/counties/changes/{id}. status"pending"always present- Always
pending. effective_atstring (date-time)always present- The organization's next anchor date, when the counties leave the set.
removalsarray of stringalways present- The counties scheduled to leave.
refusedarray of stringalways present- Named counties that were not scheduled because they are the trial county.
paid_slots_deltaintegeralways present- 0, or the negative slot change when
release_slotswas true. counties_purchased_afterintegeralways present- The paid county slot count once the batch and any release have taken effect.
active_count_afterintegeralways present- The counted total once the batch lands (counties already scheduled to leave are already left out).
slots_releasableintegeralways present- How many paid slots this removal makes spare. Not given back unless
release_slotswas true; reducing the count separately isPOST /v2/account/county-slots. notestringalways present- A plain-English summary of when the change lands and what happens to the paid count.
400 error
Bad Request. Codes: bad_request (remove missing, empty, over 200 entries, malformed or unknown entries; or none of the named counties is in the set; or the only one named is the trial county), retired_msa (an MSA the current map no longer defines), malformed_json (the body is not JSON).
As application/problem+json.
401 error
Unauthorized. Codes: unauthenticated (no valid API key or session); key_revoked (an API key that was revoked: revoked_at, and reason -- holder, admin, member_removed, seat_removed, api_disabled, addon_ended, account_closed, org_closed, retired, or null for a key revoked before T110 -- and a sentence saying when and why).
As application/problem+json.
403 error
Forbidden. Codes: role_required (owner or admin only; carries required), plan_required with entitlement: "counties_included" (the plan includes no counties), no_membership, account_suspended, org_suspended, org_closed, wrong_instance (base_url names the address that serves the key). A sandbox key: sandbox_read_only (it may write only clusters).
As application/problem+json.
404 error
Not Found. Codes: not_found (the X-DTG-Org header names no organization the caller may use).
As application/problem+json.
413 error
Payload Too Large. Codes: body_too_large (the body is over 256 KiB; carries limit_bytes).
As application/problem+json.
429 error
rate_limited (the per-minute ceiling, X-RateLimit-* say which), points_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server_busy or sandbox_busy (load; retry after Retry-After). A refused server_busy request is not metered.
As application/problem+json.
Retry-Afterheader- Seconds to wait before retrying.
X-RateLimit-Limitheader- The per-minute request ceiling that applies.
X-RateLimit-Remainingheader- Requests left in the current window.
X-RateLimit-Resetheader- Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as
Retry-After).
Problem codes: bad_request (400), retired_msa (400), malformed_json (400), unauthenticated (401), key_revoked (401), account_closed (401), org_closed (401), role_required (403), plan_required (403), no_membership (403), account_suspended (403), org_suspended (403), org_closed (403), wrong_instance (403), sandbox_read_only (403), not_found (404), body_too_large (413). Every problem is a problem document.
POST /v2/account/counties/confirm
Choose which counties to keep after an involuntary shrink (free)
Credentials: API key or App session. Operation id geoConfirmCounties.
The keep-which-counties choice owed after a downgrade or dunning shed counties (county_choice_pending on GET /v2/account/counties, D20/D44). The counties named in keep stay active, up to capacity; remaining capacity is filled with the most recently used, then most recently added; the rest are shed (read-locked, never deleted). The choice is free and clears county_choice_pending. It may also be called when no choice is pending, to re-pick the active counties within capacity. The trial county is never affected.
Credential: an API key or a session; owner or admin only. Side effect: one audit row, counties.confirmed.
Request body
Optional; application/json.
keeparray of string- Optional. The counties to keep, in the same forms as
add(5-digit FIPS,state:XX,msa:NNNNN), up to capacity, in priority order. Entries not in the set are ignored. Capacity left over is filled by the default order: most recently used in the last 90 days, then most recently added. Leave it out to accept that default.
Responses
200 success
The counties kept and shed.
As application/json.
keptarray of stringalways present- The counties active after the choice (not counting the trial county).
shedarray of stringalways present- The counties newly read-locked by this choice.
capacityintegeralways present- The capacity the choice was made against; -1 means every county.
free_swaptruealways present- Always true. This choice costs nothing.
400 error
Bad Request. Codes: bad_request (keep given but empty, over 200 entries, or holding malformed or unknown entries), retired_msa (an MSA the current map no longer defines), malformed_json (the body is not JSON).
As application/problem+json.
401 error
Unauthorized. Codes: unauthenticated (no valid API key or session); key_revoked (an API key that was revoked: revoked_at, and reason -- holder, admin, member_removed, seat_removed, api_disabled, addon_ended, account_closed, org_closed, retired, or null for a key revoked before T110 -- and a sentence saying when and why).
As application/problem+json.
403 error
Forbidden. Codes: role_required (owner or admin only; carries required), no_membership, account_suspended, org_suspended, org_closed, wrong_instance (base_url names the address that serves the key). A sandbox key: sandbox_read_only (it may write only clusters).
As application/problem+json.
404 error
Not Found. Codes: not_found (the X-DTG-Org header names no organization the caller may use).
As application/problem+json.
413 error
Payload Too Large. Codes: body_too_large (the body is over 256 KiB; carries limit_bytes).
As application/problem+json.
429 error
rate_limited (the per-minute ceiling, X-RateLimit-* say which), points_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server_busy or sandbox_busy (load; retry after Retry-After). A refused server_busy request is not metered.
As application/problem+json.
Retry-Afterheader- Seconds to wait before retrying.
X-RateLimit-Limitheader- The per-minute request ceiling that applies.
X-RateLimit-Remainingheader- Requests left in the current window.
X-RateLimit-Resetheader- Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as
Retry-After).
Problem codes: bad_request (400), retired_msa (400), malformed_json (400), unauthenticated (401), key_revoked (401), account_closed (401), org_closed (401), role_required (403), no_membership (403), account_suspended (403), org_suspended (403), org_closed (403), wrong_instance (403), sandbox_read_only (403), not_found (404), body_too_large (413). Every problem is a problem document.
DELETE /v2/account/counties/changes/{id}
Cancel a pending removal batch
Credentials: API key or App session. Operation id geoCancelCountyChange.
Cancels a pending removal batch: its counties stay in the set and count toward capacity again. Refused 409 capacity_exceeded when replacements have already taken the departing counties' slots (buy more slots or remove other counties first). If the batch was giving slots back, the paid count is restored.
Credential: an API key or a session; owner or admin only. Side effect: one audit row, counties.removal_cancelled.
Parameters
idpath · string (uuid)required- The batch id (from
POST /v2/account/counties/removeorpending_change.id).
Responses
204 success
Cancelled.
401 error
Unauthorized. Codes: unauthenticated (no valid API key or session); key_revoked (an API key that was revoked: revoked_at, and reason -- holder, admin, member_removed, seat_removed, api_disabled, addon_ended, account_closed, org_closed, retired, or null for a key revoked before T110 -- and a sentence saying when and why).
As application/problem+json.
403 error
Forbidden. Codes: role_required (owner or admin only; carries required), no_membership, account_suspended, org_suspended, org_closed, wrong_instance (base_url names the address that serves the key). A sandbox key: sandbox_read_only (it may write only clusters).
As application/problem+json.
404 error
Not Found. Codes: not_found (no pending batch with this id for this organization, a malformed id, or an X-DTG-Org header naming no organization the caller may use).
As application/problem+json.
409 error
Conflict. Codes: capacity_exceeded (cancelling would leave more counties than capacity; carries counties_after and capacity).
As application/problem+json.
429 error
rate_limited (the per-minute ceiling, X-RateLimit-* say which), points_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server_busy or sandbox_busy (load; retry after Retry-After). A refused server_busy request is not metered.
As application/problem+json.
Retry-Afterheader- Seconds to wait before retrying.
X-RateLimit-Limitheader- The per-minute request ceiling that applies.
X-RateLimit-Remainingheader- Requests left in the current window.
X-RateLimit-Resetheader- Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as
Retry-After).
Problem codes: unauthenticated (401), key_revoked (401), account_closed (401), org_closed (401), role_required (403), no_membership (403), account_suspended (403), org_suspended (403), org_closed (403), wrong_instance (403), sandbox_read_only (403), not_found (404), capacity_exceeded (409). Every problem is a problem document.
GET /v2/account/regions
Retired (D44); always 404 region_retired (deprecated)
Credentials: API key or App session. Operation id geoRegionsRetiredGet.
Retired, not aliased: a plan buys counties, and named sets are area clusters. Every method on /v2/account/regions and on any path below it answers 404 region_retired, with replaced_by naming /v2/account/counties and areas=cluster:<id>. (Authentication and the rate limit still run first, so the usual 401, 403 and 429 refusals can precede it.)
Responses
404 error
Not Found. Codes: region_retired (always; carries replaced_by).
As application/problem+json.
Problem codes: region_retired (404). Every problem is a problem document.
PUT /v2/account/regions
Retired (D44); always 404 region_retired (deprecated)
Credentials: API key or App session. Operation id geoRegionsRetiredPut.
Retired. Answers 404 region_retired on this path and any path below it; use area clusters (/v2/account/clusters).
Responses
403 error
Forbidden. sandbox_read_only (a sandbox key may write only clusters), and the authentication middleware's no_membership, account_suspended, org_suspended, org_closed, wrong_instance (base_url names the address that serves the key).
As application/problem+json.
404 error
Not Found. Codes: region_retired (always; carries replaced_by).
As application/problem+json.
Problem codes: sandbox_read_only (403), no_membership (403), account_suspended (403), org_suspended (403), org_closed (403), wrong_instance (403), region_retired (404). Every problem is a problem document.
POST /v2/account/regions
Retired (D44); always 404 region_retired (deprecated)
Credentials: API key or App session. Operation id geoRegionsRetiredPost.
Retired. Answers 404 region_retired on this path and any path below it; use POST /v2/account/counties or POST /v2/account/clusters (kind fips).
Responses
403 error
Forbidden. sandbox_read_only (a sandbox key may write only clusters), and the authentication middleware's no_membership, account_suspended, org_suspended, org_closed, wrong_instance (base_url names the address that serves the key).
As application/problem+json.
404 error
Not Found. Codes: region_retired (always; carries replaced_by).
As application/problem+json.
Problem codes: sandbox_read_only (403), no_membership (403), account_suspended (403), org_suspended (403), org_closed (403), wrong_instance (403), region_retired (404). Every problem is a problem document.
PATCH /v2/account/regions
Retired (D44); always 404 region_retired (deprecated)
Credentials: API key or App session. Operation id geoRegionsRetiredPatch.
Retired. Answers 404 region_retired on this path and any path below it; use area clusters (/v2/account/clusters).
Responses
403 error
Forbidden. sandbox_read_only (a sandbox key may write only clusters), and the authentication middleware's no_membership, account_suspended, org_suspended, org_closed, wrong_instance (base_url names the address that serves the key).
As application/problem+json.
404 error
Not Found. Codes: region_retired (always; carries replaced_by).
As application/problem+json.
Problem codes: sandbox_read_only (403), no_membership (403), account_suspended (403), org_suspended (403), org_closed (403), wrong_instance (403), region_retired (404). Every problem is a problem document.
DELETE /v2/account/regions
Retired (D44); always 404 region_retired (deprecated)
Credentials: API key or App session. Operation id geoRegionsRetiredDelete.
Retired. Answers 404 region_retired on this path and any path below it; use POST /v2/account/counties/remove or DELETE /v2/account/clusters/{id}.
Responses
403 error
Forbidden. sandbox_read_only (a sandbox key may write only clusters), and the authentication middleware's no_membership, account_suspended, org_suspended, org_closed, wrong_instance (base_url names the address that serves the key).
As application/problem+json.
404 error
Not Found. Codes: region_retired (always; carries replaced_by).
As application/problem+json.
Problem codes: sandbox_read_only (403), no_membership (403), account_suspended (403), org_suspended (403), org_closed (403), wrong_instance (403), region_retired (404). Every problem is a problem document.
Generated from taigan/openapi.yaml at catahoula 77925fab712f(API document version 2.0).