Skip to Content
GeocodingReferencePlan, usage and provider API

Plan, usage and provider API

For: developers.

Prices in USD. A month is a calendar month in UTC. Errors respond {"error": "…"}.

MethodPathWhoWhat it does
GET/api/v1/orgs/{org}/geocoding-plan?month=YYYY-MMOrganization owner or platform ownerPlan, subscription and the month’s usage
PUT/api/v1/orgs/{org}/geocoding-planPlatform ownerThe organization’s quota
GET/api/v1/platform/geocoding-planPlatform ownerThe plan
PUT/api/v1/platform/geocoding-planPlatform ownerChanges the plan
GET/api/v1/platform/geocoding-plan/usage?month=YYYY-MMPlatform ownerUsage of each organization
GET/api/v1/platform/geocoding-providerPlatform ownerThe platform’s provider
PUT/api/v1/platform/geocoding-providerPlatform ownerSets the provider
DELETE/api/v1/platform/geocoding-providerPlatform ownerRemoves the provider and keeps the credential
GET/api/v1/platform/orgs/{slug}/geocoding-connectionPlatform ownerThe organization’s connection
POST/api/v1/platform/orgs/{slug}/geocoding-connectionPlatform ownerConnects the organization to the provider
DELETE/api/v1/platform/orgs/{slug}/geocoding-connectionPlatform ownerRemoves the connection

Without month, the current month is used. A malformed month gives 400 with month must be YYYY-MM.

The plan

A single plan for the whole platform.

FieldTypeDescription
monthlyPriceUsdnumber ≥ 0Monthly price per subscribed organization
resolutionsPerMonthinteger ≥ 0Provider calls included, for a subscription without its own quota
overagePriceUsdnumber ≥ 0Price per call over the quota, only with onExhausted: "overage"
alertPct1 to 100Percentage of the quota at which an alert is sent, once per month. Default 80
enforcedbooleantrue: the quota applies. false: no call is refused
updatedBy, updatedAtRead-only

PUT /platform/geocoding-plan requires monthlyPriceUsd, resolutionsPerMonth and overagePriceUsd. If alertPct is omitted, it is 80. If enforced is omitted, it keeps its value.

400When
monthlyPriceUsd, resolutionsPerMonth and overagePriceUsd are required
prices and resolutionsPerMonth cannot be negative
alertPct must be from 1 to 100
curl -s -X PUT "$MIOT_API/api/v1/platform/geocoding-plan" \ -H "Authorization: Bearer $MIOT_TOKEN" -H "Content-Type: application/json" \ -d '{ "monthlyPriceUsd": 0, "resolutionsPerMonth": 1000, "overagePriceUsd": 0.005, "alertPct": 80, "enforced": true }'

Each change to the plan or to a subscription stores a version. The usage of a past month is calculated with the terms in force at the close of that month.

The subscription

FieldDescription
monthlyQuotaOwn quota. null uses the plan’s resolutionsPerMonth
onExhaustedreview (default): when the quota runs out, the provider is not called and the site goes to review. overage: calls continue and each extra call is charged at overagePriceUsd
curl -s -X PUT "$MIOT_API/api/v1/orgs/demo/geocoding-plan" \ -H "Authorization: Bearer $MIOT_TOKEN" -H "Content-Type: application/json" \ -d '{ "monthlyQuota": null, "onExhausted": "review" }'

Responds with the subscription: monthlyQuota, onExhausted, updatedBy, updatedAt.

400When
body is required
monthlyQuota cannot be negative
onExhausted must be review or overage

A quota of 0 with review refuses every provider call and publishes no alert. The quota alert is published even when Apply the quotas is off, only for organizations with a subscription.

A month’s usage

GET /orgs/{org}/geocoding-plan responds:

{ "plan": { "monthlyPriceUsd": 0.00, "resolutionsPerMonth": 1000, "overagePriceUsd": 0.005000, "alertPct": 80, "enforced": true, "updatedBy": "…", "updatedAt": "…" }, "subscription": { "monthlyQuota": null, "onExhausted": "review", "updatedBy": "…", "updatedAt": "…" }, "usage": { "periodStart": "2026-10-01T00:00:00Z", "periodEnd": "2026-11-01T00:00:00Z", "quota": 1000, "used": 4, "resolutions": 13, "cacheHits": 2, "providerCostUsd": null, "overageCalls": 0, "overageUsd": 0, "chargeUsd": 0.00, "bySource": [ { "source": "internal", "result": "resolved", "resolutions": 7, "cacheHits": 0, "providerCalls": 0, "providerCostUsd": null }, { "source": "provider", "result": "resolved", "resolutions": 5, "cacheHits": 2, "providerCalls": 3, "providerCostUsd": null }, { "source": "provider", "result": "needs_review", "resolutions": 1, "cacheHits": 0, "providerCalls": 1, "providerCostUsd": null } ] }, "enforced": true }
usage fieldDescription
quotaThe month’s quota. null without a subscription
usedProvider calls. This is what counts toward the quota
resolutionsResolutions from any source
cacheHitsResolutions answered by the cache
providerCostUsdWhat the provider charged the platform. null in the organization’s view
overageCallsCalls over the quota
overageUsdoverageCalls × overagePriceUsd, only with onExhausted: "overage"
chargeUsdmonthlyPriceUsd + overageUsd. null without a subscription, or in a past month without stored terms (then plan shows the current plan)
bySourceOne row per source and result. source is none if no source gave a point

GET /platform/geocoding-plan/usage responds { "organizations": [ { "organization", "subscription", "usage" } ] }, with each organization that has a subscription or usage in the month, and with providerCostUsd.

The platform’s provider

PUT /platform/geocoding-provider:

FieldDescription
providermapbox (default) or google
credentialProfileIdToken (bearer) credential in the Platform scope. If the credential is labeled with a provider, it must be the same one. Required the first time; when omitted, the current one is kept
permanentMapbox only. When omitted, it is true. With false, no provider result is used
costPerRequestUsdWhat the provider charges the platform per call. It is copied into each usage row. It is not what the organization pays. When omitted, it is cleared

Each PUT replaces provider, permanent and costPerRequestUsd. Send all three.

Responds with the view: configured, connectionId, provider, permanent, costPerRequestUsd, credentialProfileId, credentialName. The token is never returned.

400When
unknown geocoding provider X
costPerRequestUsd cannot be negative
credentialProfileId is requiredFirst time without a credential
Request body is required
(the credential’s reason)The credential is not a platform credential, is not a token credential, is managed, or is for another provider

GET without a provider responds 200 with configured: false. DELETE without a provider responds 404 with No platform geocoding provider.

An organization’s connection

POST /platform/orgs/{slug}/geocoding-connection creates, once, a managed credential and the Geocoding · ModularIoT connection in the organization. Repeating it returns the same connection. If the organization had another geocoding connection, it deletes it. DELETE deletes the connection and its managed credential. GET without a connection responds { "connected": false } with the rest in null.

Responds { "connected": true, "connectionId": "…", "name": "Geocoding · ModularIoT", "status": "ACTIVE" }.

CodeWhen
404Organization not found, or The organization has no geocoding connection on DELETE
400The platform uses its own geocoding provider connection: the slug is the platform
409Set the platform's geocoding provider in Settings › Connections, under the Platform scope, first
204Successful DELETE. From then on, the organization’s sites that need the provider go to review
Last updated on