Hyz API

The tool reference

One POST per tool, all generated from the same manifest the in-app tools run on. This page derives from the live catalog: names, parameters and flags cannot drift from the backend.

Calling a tool

Same base URL, same auth, same envelope — per tool.

Every tool is a single POST under the API base. Authentication and the response envelope are documented in the Reference; this page adds what varies per tool: the fields, the ceilings and the response.

POST https://haiyz.net/api/enterprise/v1/gis/buffer
X-Api-Key: haiyz_pk_live_xxxxxxxxxxxx
X-Api-Secret: haiyz_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
X-Api-User: [email protected]

Every tool endpoint is POST. File tools take multipart/form-data; JSON tools take an application/json body.
Multi-file inputs repeat the same form field once per file. Optional fields carry the documented default when omitted — never send the literal string "undefined".
Vector tools accept the input extensions below and produce any of: geojson, shp, kml, gml, gpkg, fgb, kmz, parquet (gpx is input-only).
Under the credit model each run costs the tool's credit cost (default: one credit per run; multi-file tools charge per file). Failed runs are never charged.

.zip .shp .dbf .shx .prj .cpg .csv .tsv .xlsx .xls .geojson .json .kml .gpx .gml .gpkg .fgb .kmz .parquet

What comes back

Two shapes: a stored file, or an inline JSON result.

File-producing tools store the output and answer with the standard envelope: the storage key, the suggested output filename, your input's key, per-tool result fields, and a usage block. Vector tools include the feature count, output CRS and geometry type:

keyoutputFilenameinputKeyusagefeatureCountcrsgeometryType

The bytes are fetched separately with the returned key (the app's download endpoint, or the run's artifact URL on the credit-model API) — Content-Disposition carries the filename.

JSON tools (coordinate conversion, measurement, point-in-polygon…) return their result inline in data — no stored file unless the tool says otherwise.

About X-Output-Filename and X-CRS

The compute engine emits per-result headers (X-Output-Filename, X-CRS, X-Feature-Count…) on the internal hop. The public API translates them into the JSON fields documented here — clients read fields, not headers. Binary downloads carry standard Content-Type/Content-Disposition/Content-Length.

Engine-wide ceilings

Safety rails that apply before any per-tool limit.

Uploads: 50 MB per file at the HTTP layer, on every tool route (per-tool limits below can be tighter).
Vector inputs: up to 500,000 features per file; a rejected file answers 422 with the reason.
Rasters: up to 40,000 px per edge and 64 bands.
Per-tool ceilings (pages, files, points, dimensions) are listed on each tool below — each value mirrors a named constant in the engine.

Convert & validate

3 tools

Geo-File Validator & Converter

POST /validate-convertasync-eligible

Validate and convert shapefiles, GeoJSON, and KML files.

Field	Type	Required	Details
`file`Input file	file	yes	vector geodata (see the accepted-extensions list above)
`target_format`Output format	string	yes	geojson \| shp \| kml \| gml \| gpkg \| fgb \| kmz \| parquet

Returnsstandard file response, plus:sourceCrsrepairedCountbbox

Limitsmax file 50 MB

CRS Transformer

POST /transform-crs/json

Transform coordinates between coordinate reference systems.

Field	Type	Required	Details
`source_crs`	string	yes
`target_crs`	string	yes
`points`	array	yes	an array of { x, y } coordinate objects

POST /transform-crs/csvmetered

Field	Type	Required
`file`	file	yes
`source_crs`	string	yes
`target_crs`	string	yes

ReturnstransformedPoints

Limitsmax 1,000 points

The JSON route is unmetered; the CSV route is metered. The catalog reports the toolKey as metered because the file path is.

Coordinate Converter

POST /convert-coordinatesunmetered

Convert lon/lat between decimal degrees (DD), degrees-minutes-seconds (DMS), and degrees-decimal-minutes (DDM).

Field	Type	Required	Details
`from_format`	string	yes	dd \| dms \| ddm
`points`	array	yes	an array of { lon, lat } objects

ReturnsfromFormatresults

Limitsmax 1,000 points

Extract data

1 tools

EXIF Extractor

POST /extract-exifasync-eligible

Extract GPS metadata from JPEG images and build a GeoJSON map.

Field	Type	Required	Details
`files`	file	yes	repeat the field once per file

ReturnsimagesinputKeysgeotaggedCounttotalCountgeojsonOutput

Limitsmax 10 imagesmax file 20 MB

Geometry

11 tools

Line to Polygon

POST /line-to-polygon

Convert a coordinate sequence into a closed polygon and compute geodetic area, perimeter, and shape statistics.

Field	Type	Required	Details
`coordinates`	array	yes	an array of [lon, lat] pairs — at least 3

POST /line-to-polygon/filemetered

Field	Type	Required	Details
`file`	file	yes

ReturnskeyinputKeystatsusage

Limitsmax 10,000 points

Geometry Simplifier

POST /simplifyasync-eligible

Reduce the number of vertices in a geo-file with Douglas–Peucker simplification.

Field	Type	Required	Details
`file`Input file	file	yes	vector geodata (see the accepted-extensions list above)
`target_format`Output format	string	yes	geojson \| shp \| kml \| gml \| gpkg \| fgb \| kmz \| parquet
`tolerance`Tolerance (degrees)	number	optional	min 0.000001 · default 0.001
`preserve_topology`Preserve topology (avoid self-intersections)	boolean	optional	default true

Returnsstandard file response, plus:verticesBeforeverticesAfter

Limitsmax file 50 MB

Convex Hull

POST /convex-hullasync-eligible

Compute the smallest convex polygon that encloses every geometry in a geo-file.

Field	Type	Required	Details
`file`Input file	file	yes	vector geodata (see the accepted-extensions list above)
`target_format`Output format	string	yes	geojson \| shp \| kml \| gml \| gpkg \| fgb \| kmz \| parquet

Returnsstandard file response, plus:inputFeatureCounthullVertices

Limitsmax file 50 MB

Centroids

POST /centroidsasync-eligible

Replace every feature with its centroid point — turn polygons or lines into a points layer.

Field	Type	Required	Details
`file`Input file	file	yes	vector geodata (see the accepted-extensions list above)
`target_format`Output format	string	yes	geojson \| shp \| kml \| gml \| gpkg \| fgb \| kmz \| parquet
`method`Point placement	string	optional	centroid \| inside · default centroid

Returnsstandard file response, plus:inputGeometryType

Limitsmax file 50 MB

Buffer Generator

POST /bufferasync-eligible

Create buffer zones around points, lines, or polygons — a fixed distance in metres, computed in the local UTM zone.

Field	Type	Required	Details
`file`Input file	file	yes	vector geodata (see the accepted-extensions list above)
`target_format`Output format	string	yes	geojson \| shp \| kml \| gml \| gpkg \| fgb \| kmz \| parquet
`distance_m`Buffer distance (metres)	number	optional	min 1 · default 100
`dissolve`Dissolve overlapping buffers into one geometry	boolean	optional	default false
`cap_style`Cap style (buffer ends)	string	optional	round \| flat \| square · default round

Returnsstandard file response, plus:dissolveddistanceM

Limitsmax file 50 MBmax distance 100 km

distance_m may be negative to shrink polygons; zero is rejected.

Dissolve

POST /dissolveasync-eligible

Merge features that share a column value into a single geometry, with an optional count, sum, mean, min or max of a second field.

Field	Type	Required	Details
`file`Input file	file	yes	vector geodata (see the accepted-extensions list above)
`target_format`Output format	string	yes	geojson \| shp \| kml \| gml \| gpkg \| fgb \| kmz \| parquet
`by`Group by column	string	optional	a column name read from `file`
`agg`Aggregate	string	optional	count \| sum \| mean \| min \| max · default count
`agg_field`Aggregate column	string	optional	a column name read from `file`

Returnsstandard file response, plus:inputFeatureCountgroupsgroupField

Limitsmax file 50 MB

Clip

POST /clipasync-eligible

Cut a layer down to a boundary layer, keeping only the parts that fall inside it.

Field	Type	Required	Details
`file`Input file	file	yes	vector geodata (see the accepted-extensions list above)
`mask`Clip boundary (polygons)	file	yes	vector geodata (see the accepted-extensions list above)
`target_format`Output format	string	yes	geojson \| shp \| kml \| gml \| gpkg \| fgb \| kmz \| parquet

Returnsstandard file response, plus:inputFeatureCountdroppedCount

Limitsmax file 50 MB

Explode Multipart

POST /explodeasync-eligible

Split multipart features into one feature per part, so every polygon or line stands on its own row.

Field	Type	Required	Details
`file`Input file	file	yes	vector geodata (see the accepted-extensions list above)
`target_format`Output format	string	yes	geojson \| shp \| kml \| gml \| gpkg \| fgb \| kmz \| parquet

Returnsstandard file response, plus:inputFeatureCountmultipartCountpartsCreated

Limitsmax file 50 MB

Repair Geometry

POST /repairasync-eligible

Fix invalid geometries — self-intersections, unclosed rings and empty shapes — so the layer loads cleanly in any GIS.

Field	Type	Required	Details
`file`Input file	file	yes	vector geodata (see the accepted-extensions list above)
`target_format`Output format	string	yes	geojson \| shp \| kml \| gml \| gpkg \| fgb \| kmz \| parquet

Returnsstandard file response, plus:inputFeatureCountinvalidBeforeinvalidAfterdroppedCount

Limitsmax file 50 MB

Concave Hull

POST /concave-hullasync-eligible

Compute a hull that follows the true shape of a point cloud more closely than a convex hull, tuned by a tightness ratio.

Field	Type	Required	Details
`file`Input file	file	yes	vector geodata (see the accepted-extensions list above)
`target_format`Output format	string	yes	geojson \| shp \| kml \| gml \| gpkg \| fgb \| kmz \| parquet
`ratio`Tightness	number	optional	min 0.05 · max 1 · default 0.3

Returnsstandard file response, plus:inputFeatureCountratiohullVertices

Limitsmax file 50 MB

Grid Generator

POST /gridasync-eligible

Generate a regular grid of square cells across a layer's extent, at a cell size you choose in metres.

Field	Type	Required	Details
`file`Input file	file	yes	vector geodata (see the accepted-extensions list above)
`target_format`Output format	string	yes	geojson \| shp \| kml \| gml \| gpkg \| fgb \| kmz \| parquet
`cell_size_m`Cell size (metres)	number	optional	min 1 · default 1000
`clip_to_extent`Clip grid to the input	boolean	optional	default false

Returnsstandard file response, plus:inputFeatureCountrowscolscellSizeM

Limitsmax file 50 MBmax cell size 5,000,000 m

Measure

3 tools

Distance & Bearing

POST /distance-bearingunmetered

Compute geodesic distance and forward/back bearing between a sequence of points.

Field	Type	Required	Details
`points`	array	yes	an array of { lon, lat } objects — at least 2

Returnssegmentstotal_distance_mtotal_distance_kmstraight_distance_mstraight_distance_kmis_closedpoint_countsegment_count

Limitsmax 1,000 points

Point-in-Polygon Checker

POST /point-in-polygonunmetered

Check whether points fall inside, outside, or on the boundary of a polygon, with geodesic distance to the nearest edge.

Field	Type	Required	Details
`polygon`	array	yes	an array of [lon, lat] pairs — at least 3
`points`	array	yes	an array of { lon, lat } objects

Returnsresultsinside_countoutside_countboundary_countpoint_count

Limitsmax 1,000 points

Area & Length

POST /area-lengthasync-eligible

Measure geodesic area and perimeter or length for every feature — accurate on the ellipsoid, not a flat approximation.

Field	Type	Required	Details
`file`Input file	file	yes	vector geodata (see the accepted-extensions list above)
`target_format`Output format	string	yes	geojson \| shp \| kml \| gml \| gpkg \| fgb \| kmz \| parquet

Returnsstandard file response, plus:inputFeatureCounttotalAreaM2totalLengthMmeasuredAreasmeasuredLengths

Limitsmax file 50 MB

Combine

2 tools

Geo-File Merger

POST /mergeasync-eligible

Merge 2–5 geo-files (shapefile, GeoJSON, KML) into a single layer with a unified CRS — each feature tagged with its source file.

Field	Type	Required	Details
`files`Files to merge (2–5)	file	yes	vector geodata (see the accepted-extensions list above) · 2–5 files
`target_format`Output format	string	yes	geojson \| shp \| kml \| gml \| gpkg \| fgb \| kmz \| parquet

Returnsstandard file response, plus:fileCount

Limitsmin 2 filesmax 5 filesmax file 50 MB

Spatial Join

POST /spatial-joinrequires plusasync-eligible

Attach the attributes of one layer to another by spatial relationship — intersects, within, contains, crosses, touches or overlaps.

Field	Type	Required	Details
`file`Input file	file	yes	vector geodata (see the accepted-extensions list above)
`join`Layer to join from	file	yes	vector geodata (see the accepted-extensions list above)
`target_format`Output format	string	yes	geojson \| shp \| kml \| gml \| gpkg \| fgb \| kmz \| parquet
`predicate`Spatial relationship	string	optional	intersects \| within \| contains \| crosses \| touches \| overlaps · default intersects
`how`Keep unmatched features	string	optional	inner \| left · default inner

Returnsstandard file response, plus:inputFeatureCountjoinFeatureCountmatchedCountpredicate

Limitsmax file 50 MB

Raster & imagery

3 tools

Raster Inspector & Preview

POST /raster-inspectasync-eligible

Upload a GeoTIFF/DEM to see its CRS, bounds, resolution, and per-band statistics, plus a quick preview image.

Field	Type	Required	Details
`file`	file	yes

ReturnsinputKeypreviewKeypreviewPngB64crswidthheightbandCountresolutionboundsbandsusage

Limitsmax file 50 MB

COG Validator & Optimizer

POST /cog-optimizeasync-eligible

Upload a GeoTIFF to check whether it's a Cloud-Optimized GeoTIFF (tiled + overviews) and download an optimized copy.

Field	Type	Required	Details
`file`Raster (GeoTIFF)	file	yes	GeoTIFF (.tif, .tiff, .geotiff)

Returnsstandard file response, plus:wasAlreadyCogissueswidthheightbandCountoriginalTiledoriginalOverviewCountoriginalCompressionoptimizedOverviewCountoptimizedCompression

Limitsmax file 50 MB

Zonal Statistics

POST /zonal-statsrequires plusasync-eligible

Summarise raster values inside each polygon zone — mean, min, max, sum and count per feature.

Field	Type	Required	Details
`file`Zone polygons	file	yes	vector geodata (see the accepted-extensions list above)
`raster`Raster (GeoTIFF)	file	yes	GeoTIFF (.tif, .tiff, .geotiff)
`target_format`Output format	string	yes	geojson \| shp \| kml \| gml \| gpkg \| fgb \| kmz \| parquet
`band`Raster band	number	optional	min 1 · default 1
`stats`Statistics	string	yes

Returnsstandard file response, plus:inputFeatureCountzoneszonesWithDatabandstats

Limitsmax file 50 MBmax 2,000 zones

Image tools

5 tools

Background Remover

POST /remove-background

Remove the background from a photo automatically, right in your browser.

Field	Type	Required	Details
`file`Image	file	yes	PNG, JPEG, WebP, BMP

Returnsstandard file response, plus:

Limitsmax file 20 MBmax 6,000 px per side

Image Quality Enhancer

POST /enhance-quality

Sharpen and re-encode an image for a cleaner result — Plus members get full resolution, higher quality, and an optional 2× upscale.

Field	Type	Required	Details
`file`Image	file	yes	PNG, JPEG, WebP, BMP, TIFF, GIF
`upscale`2× upscale	boolean	optional	default false

Image Format Converter

POST /convert-format

Convert an image between PNG, JPG, WebP, BMP, TIFF, and GIF.

Field	Type	Required	Details
`file`Image	file	yes	PNG, JPEG, WebP, BMP, TIFF, GIF
`target_format`Target format	string	optional	png \| jpeg \| webp \| bmp \| tiff \| gif · default png

Watermark Image

POST /image-watermark

Add a text or logo watermark to a photo or graphic.

Field	Type	Required	Details
`file`Image	file	yes	PNG, JPEG, WebP, BMP, TIFF, GIF
`wm_mode`Watermark type	string	optional	text \| image · default text
`text`Watermark text	string	yes
`logo`Image to stamp	file	yes	PNG, JPEG, WebP, BMP, TIFF, GIF
`position`Position	string	optional	diagonal \| center \| top-left \| top-right \| bottom-left \| bottom-right · default bottom-right
`opacity`Opacity	number	optional	min 0.05 · max 1 · default 0.4

Returnsstandard file response, plus:

Limitsmax file 20 MBmax logo 5 MBmax 8,000 px per sidemax 80 characters

Provide exactly one of text or logo — the engine rejects both or neither.

Merge Images

POST /merge-images

Stitch multiple images into one — stacked, side by side, or as a grid.

Field	Type	Required	Details
`files`Images	file	yes	PNG, JPEG, WebP, BMP, TIFF, GIF · 2–12 files
`layout`Layout	string	optional	vertical \| horizontal \| grid · default vertical

Returnsstandard file response, plus:fileCountwidthheight

Limitsmin 2 filesmax 12 filesmax file 20 MBmax 8,000 px per side

Document tools

11 tools

OCR — Extract Text from Image

POST /ocr

Extract text from a photo or scan — supports English, Arabic, or both together.

Field	Type	Required	Details
`file`	file	yes
`lang`	string	optional	eng \| ara \| eng+ara · default eng

ReturnskeyinputKeytextlangcharCountusage

Limitsmax file 20 MBmax 8,000 px per side

PDF to Word

POST /pdf-to-word

Convert a PDF's text and layout into an editable Word document.

Field	Type	Required	Details
`file`PDF file	file	yes	PDF

Returnsstandard file response, plus:

Limitsmax file 30 MBmax 200 pages

Sign a document

POST /document-sign

Place your signature on a PDF — draw it, upload it, or reuse a saved one.

Field	Type	Required	Details
`file`	file	yes
`signature`	file	yes	PNG only
`placements`	json-string	yes	a JSON string: an array of { page, x, y, w, h } boxes in page fractions (0–1)

Returnsstandard file response, plus:

Limitsmax file 30 MBmax signature 512 KBmax 200 pagesmax 250 placements

This stamps a signature image into the pages — it is not a certified digital signature.

Merge PDF

POST /merge-pdf

Combine up to 20 PDFs into one document, in the order you choose.

Field	Type	Required	Details
`files`PDF files (2–20)	file	yes	PDF · 2–20 files

Returnsstandard file response, plus:fileCountpageCount

Limitsmin 2 filesmax 20 filesmax file 30 MBmax 500 pages per filemax 1,500 pages total

Split PDF

POST /split-pdf

Extract pages or page ranges from a PDF — as one part or several.

Field	Type	Required	Details
`file`PDF file	file	yes	PDF
`ranges`Pages to extract	string	yes

Returnsstandard file response, plus:partCount

Limitsmax file 30 MBmax 1,000 pagesmax 50 ranges

A single range returns a PDF; several ranges return a ZIP (the real name is in outputFilename).

Compress PDF

POST /compress-pdf

Shrink a PDF's file size by re-encoding its images and cleaning up its structure.

Field	Type	Required	Details
`file`PDF file	file	yes	PDF
`quality`Quality	string	optional	screen \| ebook \| print · default ebook

Returnsstandard file response, plus:pageCountoriginalBytescompressedBytesalreadyOptimized

Limitsmax file 50 MBmax 1,000 pages

PDF to Images

POST /pdf-to-images

Render each page of a PDF as a high-quality PNG image.

Field	Type	Required	Details
`file`PDF file	file	yes	PDF
`dpi`Resolution (DPI)	string	optional	72 \| 150 \| 300 · default 150

Returnsstandard file response, plus:pageCount

Limitsmax file 30 MBmax 100 pages

Always returns a ZIP of page images.

Watermark PDF

POST /pdf-watermark

Stamp text or a logo across every page of a PDF.

Field	Type	Required	Details
`file`PDF file	file	yes	PDF
`wm_mode`Watermark type	string	optional	text \| image · default text
`text`Watermark text	string	yes
`logo`Image to stamp	file	yes	PNG, JPEG, WebP, BMP, TIFF, GIF
`position`Position	string	optional	diagonal \| center \| top-left \| top-right \| bottom-left \| bottom-right · default diagonal
`opacity`Opacity	number	optional	min 0.05 · max 1 · default 0.15

Returnsstandard file response, plus:pageCount

Limitsmax file 30 MBmax 500 pagesmax logo 5 MBmax 80 characters

Provide exactly one of text or logo — the engine rejects both or neither.

Images to PDF

POST /images-to-pdf

Turn photos and scans into a single PDF, one image per page.

Field	Type	Required	Details
`files`Images	file	yes	PNG, JPEG, WebP, BMP, TIFF, GIF · 1–20 files
`page_mode`Page size	string	optional	a4 \| fit · default a4

Returnsstandard file response, plus:pageCountfileCount

Limitsmin 1 filesmax 20 filesmax file 20 MBmax 8,000 px per side

Fill PDF Form

POST /fill-pdf

Type into a PDF's own form fields and download the filled document.

Field	Type	Required	Details
`file`	file	yes
`values`	json-string	yes	a JSON string: an object of AcroForm field name → value (up to the form-values limit)
`flatten`	string	optional	true \| false · default false

Returnsstandard file response, plus:fieldCountfilledCountflattened

Limitsmax file 30 MBmax 500 pagesmax 500 form values

Rotate & Delete Pages

POST /rotate-pages

Fix page orientation and drop unwanted pages, right on the thumbnails.

Field	Type	Required	Details
`file`	file	yes
`operations`	json-string	yes	a JSON string: { "rotations": { "<page>": 90\|180\|270 }, "delete": [pages] } — pages are 0-based; at least one operation

Returnsstandard file response, plus:pageCountrotatedCountdeletedCount

Limitsmax file 30 MBmax 100 pages

Embedded tools (API-only)

In the manifest, not in the catalog.

Two tools have no standalone page and never appear in the browsable catalog — they are invoked from inside other surfaces, and over the API. They are gated and metered like every other tool.

Workspace export

POST /workspace-exportrequires freeembedded

Convert the workspace's visible layers to Shapefile, KML or CSV.

Field	Type	Required	Details
`file`	file	yes	the workspace layer as GeoJSON
`target_format`	string	yes	shp \| kml \| csv \| geojson
`base_name`	string	optional

ReturnsfeatureCounttruncatedFields

Limitsmax file 50 MB

Map export

POST /map-exportenterprise workspaces onlyembedded

Compose a print-ready map sheet with a title, legend and north arrow.

Field	Type	Required	Details
`image`	file	yes	repeat the field once per fileone PNG capture per map block, repeated
`logo`	file	optional
`spec`	json-string	yes	a JSON string describing the sheet: page (a4\|a3\|letter), orientation, title, legend items, attribution, CRS label and more

Limitsmax capture 25 MBmax logo 2 MBmax 64 legend items