Geospatial API · USDC over x402 · Base Sepolia

Geometry,
sold by the call.

Give an agent one URL for reprojection, GeoJSON repair, geometry, H3, timezone, and Census lookups. No account, API key, or subscription. Each request costs $0.001 to $0.01 and settles in USDC.

Browse the endpoints Inspect a paid request

paid routes: 17
a call: $0.001–$0.01
EPSG codes: 1,236
free routes: 2

The actual index behind GET /v1/timezone. 2,398 H3 cells, coloured by UTC offset on 2026-08-20. The bright meridian marks solar noon right now.

Testnet. Every route currently settles on Base Sepolia in testnet USDC. Real money arrives with the mainnet cutover; the sandbox stays at sandbox.geoprimitives.dev afterwards.

A paid request

From request to answer in three steps.

The request, payment terms, and response below were captured from the live API when this page was built.

1 Ask

POST https://api.geoprimitives.dev/v1/hello
content-type: application/json

{"name":"world"}

The request carries no credentials. Anyone can send it.

2 402 Payment Required

HTTP/2 402
content-type: application/json
payment-required: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQYXlt…

{}

The body is {}. The terms are the header, base64 JSON, recorded from the live API when this page was built:

{
  "x402Version": 2,
  "resource": {
    "url": "https://api.geoprimitives.dev/v1/hello",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:84532",
      "amount": "1000",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "payTo": "0x42b5882F9Fb35bC1014416F1637F351421151cb5",
      "maxTimeoutSeconds": 300
    }
  ]
}

1000 atomic 0x036CbD53842c5426634e7929541eC2318f3dCF7e is $0.001. The 402 and the catalog are generated from one price table, and this build checked that they agree. Omitted above for length: resource.description, which is the same prose the docs carry, and extensions.bazaar, the Bazaar discovery block that tells an agent what to send.

3 Pay, retry, served
```
POST https://api.geoprimitives.dev/v1/hello
payment-signature: <EIP-3009 transferWithAuthorization, signed>

HTTP/2 200
payment-response: {"success":true,"transaction":"0x…","network":"eip155:84532"}

{"hello":"world", …}
```
The facilitator submits the transaction, so the buyer holds USDC and needs no gas. Each authorization nonce is single-use at the token contract, so a replayed signature is rejected there. First settlement on this route, read off the chain: 0xf9e26c83…0199c0.

Endpoints and prices

17 paid routes. Two price tiers.

The Worker generates both its payment quotes and /openapi.json from the same price table. The amounts below are read from that catalog at build time.

Route	What it does	Price
HandshakeProve a client can pay before it spends anything real.
POST `/v1/hello`	Echo a string back. The cheapest way to test your payment client.	$0.001
GeoJSONValidate against RFC 7946, or repair into it.
POST `/v1/geojson/validate`	Check GeoJSON against RFC 7946 and say exactly what is wrong and where.	$0.005
POST `/v1/geojson/repair`	Rewrite broken GeoJSON into RFC 7946 form and log every change.	$0.01
ReprojectionCoordinates between EPSG codes, PROJ-checked.
POST `/v1/transform`	Reproject coordinates or GeoJSON between 1236 EPSG codes.	$0.005
GeometryPolygon operations computed on the WGS 84 ellipsoid.
POST `/v1/geometry/buffer`	Offset a geometry by a distance in metres, corrected for the ellipsoid.	$0.01
POST `/v1/geometry/simplify`	Thin out vertices with Douglas-Peucker, in metres or in degrees.	$0.01
POST `/v1/geometry/union`	Merge two or more polygons into one shape.	$0.01
POST `/v1/geometry/intersect`	Return the area two or more polygons have in common.	$0.01
POST `/v1/geometry/difference`	Subtract later polygons from the first one. Order matters.	$0.01
POST `/v1/geometry/area`	Ellipsoidal area of a polygon in square metres, holes subtracted.	$0.01
POST `/v1/geometry/centroid`	True area centroid of a polygon, weighted correctly at high latitude.	$0.01
POST `/v1/geometry/bbox`	Extent of any geometry as [minLon, minLat, maxLon, maxLat].	$0.01
H3 gridPoints to cells, polygons to cell sets.
POST `/v1/h3/index`	Index positions to their containing H3 cell, at one or more resolutions.	$0.005
POST `/v1/h3/polyfill`	Cover a polygon with the set of H3 cells that tile it.	$0.01
ContainmentMany points against many polygons, the whole matrix.
POST `/v1/pip`	Test many points against many polygons and get the full matrix.	$0.01
LookupA coordinate in, a fact about that place out.
GET `/v1/timezone`	IANA timezone, current UTC offset and DST flag for a coordinate.	$0.005
GET `/v1/us/geographies`	US Census FIPS codes for a coordinate: state, county and congressional district.	$0.01
CatalogFree, always, so an agent can read before it decides to pay.
GET `/`	Service catalog: every route, its price, and what it does.	free
GET `/openapi.json`	This OpenAPI 3.1 document. Free, and generated from the price table.	free

Per-position work costs $0.005. Operations that may return large geometries cost $0.01. /v1/hello is the $0.001 payment-client check.

Use the API

Start with a URL, not an account.

From a shell

Ask without paying and read the terms out of the header.

curl -X POST https://api.geoprimitives.dev/v1/hello \
  -H 'content-type: application/json' \
  -d '{"name":"world"}' -i

From an agent

With @x402/fetch and a wallet holding USDC. The facilitator pays the gas.

import { wrapFetchWithPayment } from "@x402/fetch";

const fetchPaid = wrapFetchWithPayment(fetch, signer);
const res = await fetchPaid(
  "https://api.geoprimitives.dev/v1/timezone?lat=40.7128&lon=-74.006",
);
const { timezone, utcOffset, isDST } = await res.json();

Discover

GET / the catalog, free
GET /openapi.json OpenAPI 3.1 with a request, a response and a real answer on every route
MCP server coming; until then the OpenAPI document is the tool definition
Every 402 carries the x402 Bazaar discovery extension, so an agent that has only the URL learns the schema from the refusal

Methods and data

Answers you can trace and check.

Checked independently

Reprojection is tested against PROJ 9.5; area and buffer against GeographicLib; timezones against IANA; and Census codes against 650 Census Bureau geocoder results. Known misses are named in the route docs before you pay.

Public-domain data only

Lookup boundaries come from US government works and CC0 sources. The timezone map dates from 2016; the four regions that changed since then are disclosed in the route docs. See every source and licence.

Limits published up front

Every enforced limit is also published as machine-readable route data. Requests that cannot be served are rejected before payment, so invalid size or shape never reaches settlement.

Geometry,sold by the call.