Reference

Hyz API reference

Everything needed to make the first call and read the answer: the base URL, both authentication forms, how a run is attributed to a member, and each endpoint's fields, response and curl.

Base URL

Every call goes to this base URL with the tool's own segment appended — the last part of each path shown below. The curl samples carry the complete URL, ready to paste.

https://haiyz.net/api/enterprise/v1/gis

Every endpoint documented here is a POST, and each one carries its input in the request body.
File tools take multipart form fields, exactly as the in-app tools submit them; only the JSON reprojection endpoint takes a JSON body.
HTTPS only, and credentials travel in headers — never in the query string, where proxies and access logs would keep them.

Response envelope

Responses use the platform's standard envelope: ok says whether the call worked, code is a stable machine-readable identifier, message is human-facing text, and data carries the tool's own result.

{
  "ok": true,
  "statusCode": 200,
  "code": "SUCCESS",
  "data": {
    "key": "gis/2026/08/… .geojson",
    "inputKey": "gis/2026/08/… .zip",
    "filename": "parcels.geojson"
  },
  "path": "/enterprise/v1/gis/validate-convert",
  "method": "POST",
  "timestamp": "2026-08-17T09:41:22.104Z"
}

Tools that produce a file return a storage key for it rather than a public URL. The output is stored under the member the run was attributed to and appears in that member's file history in the app, where it can be downloaded or handed to the other Haiyz products.

Authentication

Send your credentials as headers on every request:

X-Api-Key — your public key (starts with haiyz_pk_).
X-Api-Secret — your secret key (starts with haiyz_sk_).
X-Api-User — optional; the email of the assigned member to attribute the run to. Defaults to the org owner.

Authorization: Bearer

The header pair can be replaced by a single Authorization header carrying the public key and the secret separated by a colon. It authenticates identically — pick whichever your client configures more cleanly.

curl -X POST https://haiyz.net/api/enterprise/v1/gis/validate-convert \
  -H "Authorization: Bearer haiyz_pk_live_xxxxxxxxxxxx:haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "[email protected]" \
  -F "target_format=geojson"

Keep the secret server-side

The secret is compared in constant time and stored hashed, so it cannot be shown to you again after creation. It belongs in a server-side environment variable — never in browser code, a mobile bundle or a repository. If one leaks, create a replacement key and revoke the old one; there is no in-place rotation.

Attribution

Which member of your organization a run belongs to.

Omit X-Api-User and the run is attributed to the organization owner.
The email you send must belong to an active member of the organization. Anything else is refused with ENTERPRISE_API_USER_NOT_ASSIGNED.
The run is recorded as that member's own work: the stored output and the usage row appear in their history in the app, exactly as if they had run the tool there.
In parallel, the organization's ledger records the files the run spent, per key and per window — which is what the console's usage breakdowns are built from.

Endpoints

All endpoints are POST under /enterprise/v1/gis. Request and response bodies match the in-app GIS tools.

Each section below gives the wire contract: the fields the request carries, what comes back, and a curl you can paste once you have replaced the placeholder credentials.

POST/enterprise/v1/gis/validate-convert

Validate and convert

Validate and convert a shapefile, GeoJSON or KML

Reads the uploaded vector file, checks that it is well formed, and writes it out in the format you asked for. This is what an intake pipeline calls first, so everything downstream can assume one format.

Requestmultipart/form-data

filefilerequired: The input file. One vector file per request — a zipped Shapefile, GeoJSON or KML.
target_formatstringrequired: Format to write the output in, for example geojson.

Response

Returns the storage key of the converted file, the key of the input it was produced from, and the output filename.

key
inputKey
filename

curl

curl -X POST https://haiyz.net/api/enterprise/v1/gis/validate-convert \
  -H "X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx" \
  -H "X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "[email protected]" \
  -F "target_format=geojson"

POST/enterprise/v1/gis/transform-crs/json

Reproject coordinates (JSON)

Reproject coordinate pairs (JSON in, JSON out)

Takes coordinate pairs in the request body and returns them in the target coordinate system. No file is produced, which makes it the lightest call on the surface: it counts as a single file against the window however many points it carries.

Requestapplication/json

source_crsstringrequired: Coordinate system the input is in, as an EPSG code — for example EPSG:4326.
target_crsstringrequired: Coordinate system to produce, as an EPSG code — for example EPSG:3857.
pointsarrayrequired: The coordinate pairs to reproject, as an array of objects carrying x and y.

Response

Returns the reprojected pairs in the order they were sent, as transformedPoints.

transformedPoints

curl

curl -X POST https://haiyz.net/api/enterprise/v1/gis/transform-crs/json \
  -H "X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx" \
  -H "X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Api-User: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
    "source_crs": "EPSG:4326",
    "target_crs": "EPSG:3857",
    "points": [{ "x": 46.72, "y": 24.68 }]
  }'

POST/enterprise/v1/gis/transform-crs/csv

Reproject a CSV

Reproject a CSV of coordinates

The same reprojection for a file of coordinates: upload the CSV, name the two coordinate systems, and a converted CSV is written out.

Requestmultipart/form-data

filefilerequired: The input file. One vector file per request — a zipped Shapefile, GeoJSON or KML.
source_crsstringrequired: Coordinate system the input is in, as an EPSG code — for example EPSG:4326.
target_crsstringrequired: Coordinate system to produce, as an EPSG code — for example EPSG:3857.

Response

Returns the storage keys of the output and the input, the output filename, and how many points were converted.

key
inputKey
outputFilename
pointCount

curl

curl -X POST https://haiyz.net/api/enterprise/v1/gis/transform-crs/csv \
  -H "X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx" \
  -H "X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "[email protected]" \
  -F "source_crs=EPSG:4326" \
  -F "target_crs=EPSG:32638"

POST/enterprise/v1/gis/buffer

Buffer

Buffer geometries by a distance

Grows every geometry in the file by a distance in metres — protection zones, setbacks, catchment rings. Set dissolve when overlapping rings should become one area instead of many.

Requestmultipart/form-data

filefilerequired: The input file. One vector file per request — a zipped Shapefile, GeoJSON or KML.
distance_mnumberrequired: Buffer distance in metres.
target_formatstringrequired: Format to write the output in, for example geojson.
dissolvebooleanoptional: Merge overlapping buffers into a single geometry instead of keeping one per feature.

Response

Returns the storage key of the buffered file, the key of the input, and the output filename.

key
inputKey
filename

curl

curl -X POST https://haiyz.net/api/enterprise/v1/gis/buffer \
  -H "X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx" \
  -H "X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "[email protected]" \
  -F "distance_m=100" \
  -F "target_format=geojson" \
  -F "dissolve=false"

POST/enterprise/v1/gis/merge

Merge

Merge multiple vector files

Combines several vector files into one. This is the call for datasets that arrive split by district, by sheet or by contractor while everything downstream expects a single layer.

Requestmultipart/form-data

filesfilerequired: The input files.Repeat the field once per file.
target_formatstringrequired: Format to write the output in, for example geojson.

Response

Returns the storage key of the merged file and its filename.

key
filename

curl

curl -X POST https://haiyz.net/api/enterprise/v1/gis/merge \
  -H "X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx" \
  -H "X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "target_format=geojson"

POST/enterprise/v1/gis/simplify

Simplify

Simplify geometries to a tolerance

Reduces vertex count against a tolerance — the call that makes a heavy boundary layer usable on the web. Leave preserve_topology on unless self-intersections are acceptable in the output.

Requestmultipart/form-data

filefilerequired: The input file. One vector file per request — a zipped Shapefile, GeoJSON or KML.
tolerancenumberrequired: Simplification tolerance, expressed in the units of the data's own coordinate system.
target_formatstringrequired: Format to write the output in, for example geojson.
preserve_topologybooleanoptional: Keep geometries valid while simplifying, at the cost of a little less reduction.

Response

Returns the storage key of the simplified file, the key of the input, and the output filename.

key
inputKey
filename

curl

curl -X POST https://haiyz.net/api/enterprise/v1/gis/simplify \
  -H "X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx" \
  -H "X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "[email protected]" \
  -F "tolerance=0.001" \
  -F "target_format=geojson" \
  -F "preserve_topology=true"

POST/enterprise/v1/gis/extract-exif

Extract GPS from photographs

Extract GPS EXIF from photos into GeoJSON

Reads EXIF from uploaded JPEGs and turns whatever GPS it finds into points. Photographs without location data are reported rather than dropped, so a field team can see which shots need attention.

Requestmultipart/form-data

filesfilerequired: The input files.Repeat the field once per file.

Response

Returns a row per photograph — filename, whether it carried GPS, latitude, longitude, altitude and timestamp — plus the geotagged and total counts and the key of the produced GeoJSON.

images
geotaggedCount
totalCount
geojsonOutput

curl

curl -X POST https://haiyz.net/api/enterprise/v1/gis/extract-exif \
  -H "X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx" \
  -H "X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "[email protected]" \
  -F "[email protected]"

Errors, limits and quotas

The failures this API returns, the rolling file window, the size ceilings and the retry behaviour.

Open errors & limits

{ "ok": true, "statusCode": 200, "code": "SUCCESS", "data": { "key": "gis/2026/08/… .geojson", "inputKey": "gis/2026/08/… .zip", "filename": "parcels.geojson" }, "path": "/enterprise/v1/gis/validate-convert", "method": "POST", "timestamp": "2026-08-17T09:41:22.104Z" }

curl -X POST https://haiyz.net/api/enterprise/v1/gis/validate-convert \ -H "Authorization: Bearer haiyz_pk_live_xxxxxxxxxxxx:haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \ -F "[email protected]" \ -F "target_format=geojson"

curl -X POST https://haiyz.net/api/enterprise/v1/gis/validate-convert \ -H "X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx" \ -H "X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \ -F "[email protected]" \ -F "target_format=geojson"

curl -X POST https://haiyz.net/api/enterprise/v1/gis/transform-crs/json \ -H "X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx" \ -H "X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \ -H "X-Api-User: [email protected]" \ -H "Content-Type: application/json" \ -d '{ "source_crs": "EPSG:4326", "target_crs": "EPSG:3857", "points": [{ "x": 46.72, "y": 24.68 }] }'

curl -X POST https://haiyz.net/api/enterprise/v1/gis/transform-crs/csv \ -H "X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx" \ -H "X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \ -F "[email protected]" \ -F "source_crs=EPSG:4326" \ -F "target_crs=EPSG:32638"

curl -X POST https://haiyz.net/api/enterprise/v1/gis/buffer \ -H "X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx" \ -H "X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \ -F "[email protected]" \ -F "distance_m=100" \ -F "target_format=geojson" \ -F "dissolve=false"

curl -X POST https://haiyz.net/api/enterprise/v1/gis/merge \ -H "X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx" \ -H "X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \ -F "[email protected]" \ -F "[email protected]" \ -F "target_format=geojson"

curl -X POST https://haiyz.net/api/enterprise/v1/gis/simplify \ -H "X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx" \ -H "X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \ -F "[email protected]" \ -F "tolerance=0.001" \ -F "target_format=geojson" \ -F "preserve_topology=true"

curl -X POST https://haiyz.net/api/enterprise/v1/gis/extract-exif \ -H "X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx" \ -H "X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \ -F "[email protected]" \ -F "[email protected]"