Tool APIs

One GIS tool saved as your own API — its settings fixed, its second input one of your data items — and called by another system with a key of its own.

What a Tool API is

A Tool API is one GIS tool saved as the API of a person on Pro or Max, or of an enterprise. Its settings are fixed, and the tool's second input is bound to one of the owner's own data items: read live as its Hyz Layer — an edit shows on the next call — or as a file, the newest version scanned clean at each call or a pinned one. Another system calls it with a key of its own, sends only the main input as GeoJSON and reads JSON back.

The owner's example is “inside Saudi Arabia”: the inside check, with the Saudi border bound as its reference and a rule — wholly inside, partly inside, or at least a share inside.

Any vector tool whose main input is one layer and whose output is a layer can be saved this way: the geometry tools, the intersect and union overlays, calculate geometry, validate, spatial join, zonal statistics and the inside check. Raster, image and document tools cannot.

The bound input is the tool's second one: the mask of clip and erase, the overlay layer of intersect and union, the join layer of spatial join, the raster of zonal statistics, the reference of the inside check.

In beta

Tool APIs are a beta feature, on Haiyz Cloud first. The Portal and the Console show them only where they are switched on.

Making one

A person makes theirs in the Portal; an enterprise makes its own in the Console.

In the Portal, under Toolbox › Tool APIs: choose the tool, set its settings and bind its second input to one of your data items — read live or as a file — or upload a new layer, which becomes editable once it is online and is marked as made for the API. The key is made at once and shown with a first call ready to paste. Each Tool API has its own page, and its layer opens on a page of its own: the map and its values.
Or choose Save as API, under the run button on a tool's page: it opens the same form with that tool and the settings already on the page.
In the Console, under Tool APIs: the same for an enterprise, with the enterprise's data items bound. Its owners and administrators make and manage them, and every member sees them and their traffic. A key is issued and revoked with a fresh confirmation.
On Haiyz Enclave, Tool APIs are an add-on named in the licence, priced on their own. The enterprise's owners and administrators make them, and give the Tool API creator role to anyone else who may.
Each Tool API has at most one key of its own. It is shown once and only a hash of it is kept; the owner can replace or revoke it. It opens this API's call and nothing else, and it signs no one in.
A Tool API is shared like a data item or a map: with a person, a group or a whole enterprise, as viewer (it, its traffic and what came through it), editor (also its settings and layer) or manager (also sharing and its key). Deleting it stays its owner's.
The owner can switch the API off and on, change its settings and layer, delete it, see its traffic — calls a day by status, refusals and why, response times, kept until the owner deletes the history — and read its call history for as long as it keeps call data.

Calling a Tool API

One request with the API's own key. The caller sends only the main input; the settings and the bound layers are already saved.

POST/tool-apis/{id}/run

Append the path to the API's base address, with the Tool API's own id in it:

https://haiyz.net/api

Headers

Authorization: Bearer hyzapi_…: The API's own key, which begins hyzapi_. An unknown API, no key, a revoked key and a wrong one all get the same 401.
Content-Type: application/json: The body is JSON.

Bodyapplication/json

inputGeoJSONrequired: A GeoJSON Feature, FeatureCollection or geometry: at most 10,000 features, in a request body of at most 1 MB.

Example: is this point inside Saudi Arabia?

A point in Riyadh, sent to a Tool API made of the inside check with the Saudi border as its reference. Set TOOL_API_ID to the API's id and TOOL_API_KEY to its key.

curl -X POST "https://haiyz.net/api/tool-apis/$TOOL_API_ID/run" \
  -H "Authorization: Bearer $TOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"type":"Point","coordinates":[46.7,24.7]}}'

What comes back

What the answer holds depends on the tool: a geometry tool returns its result, the inside check returns a verdict for each feature.

Every answer comes in the platform's standard envelope — ok, code and, on success, data — which the reference describes once. Read about the envelope

A geometry tool

Every tool but the inside check answers with its result as GeoJSON in data:

featureCount: How many features the result holds.
result: The result, as a GeoJSON FeatureCollection.

The inside check

The inside check answers with its verdicts in data:

passed: Whether every input feature passed the rule.
counts: How many input features were inside, partial and outside, and how many passed.
results: One verdict for each input feature.

Each entry of results is one input feature:

results[].index: The feature's position in the input, counted from 0.
results[].relation: inside, partial or outside — see how the inside check decides, below.
results[].percentInside: The share of the feature that lies inside the reference, from 0 to 100.
results[].pass: Whether this feature passed the rule.
results[].matchCount: How many reference features it overlaps.
results[].reference: The fields the owner picked, from the reference feature it overlaps most.

Example: the inside check's answer

The answer to the call above: the point lies inside, so it passes the rule, and reference carries the field the owner picked from the Saudi border.

{
  "ok": true,
  "statusCode": 200,
  "code": "TOOL_API_RESULT",
  "data": {
    "passed": true,
    "counts": { "inside": 1, "partial": 0, "outside": 0, "passed": 1 },
    "results": [
      {
        "index": 0,
        "relation": "inside",
        "percentInside": 100,
        "pass": true,
        "matchCount": 1,
        "reference": { "name": "Saudi Arabia" }
      }
    ]
  }
}

How the inside check decides

Each input feature is compared with the bound polygon reference layer.

Relation

inside: Wholly within the reference. The border counts as inside.
partial: Overlaps the reference without lying wholly within it. A feature that only touches the edge is outside.
outside: Does not overlap the reference.

percentInside is the share of a polygon's area, a line's length or a multipoint's points that lies inside, measured in an equal-area projection. A point is 100 or 0.

The rule the owner fixes

inside: A feature passes when it is wholly inside.
partial: A feature passes on any overlap.
percent ≥ N: A feature passes when its percentInside is at least N.

reference holds the fields the owner picked from the reference feature the input overlaps most — which region it falls in, for example.

Limits and allowance

A call counts as one API request against its owner's daily allowance — not as a tool run.

10,000features: At most, in one call's input.
1MB: The largest request body a call may send.
60a minute: Calls to one Tool API, at most.
1API request: What one call counts against its owner's day.
25Tool APIs: At most, for one owner.

A person's calls count against their plan's API requests a day, which their personal API keys share. An enterprise's calls count against its tier's API requests a day.

The bound layers stay inside

The layers a Tool API is bound to never leave the platform: a caller cannot read them through the API. A caller of “inside Saudi Arabia” gets verdicts, not the border.

What the owner keeps

The owner of a Tool API may keep what each call sends, what it answered and the caller's IP address, for 30, 90 or 365 days, to read and export — or keep nothing but the call's outcome. Send only what the check needs.

Errors

The codes a call can answer with, and what each one means.

400TOOL_API_INPUT_INVALID

The input is not a usable GeoJSON Feature, FeatureCollection or geometry. The message says why.

401TOOL_API_KEY_INVALID

The API is unknown, or the key is missing, revoked or wrong. All four get the same answer.

403TOOL_API_DISABLED

The owner has switched this Tool API off.

403TOOL_API_PLAN

The owner is no longer on a plan or tier that includes Tool APIs. The API answers again once they are.

403TOOL_API_SUSPENDED

The owner's account or enterprise is suspended. The API answers no calls while it is.

403TOOL_API_HELD

Haiyz has switched this Tool API off. It answers no calls until Haiyz releases it; its owner is told why.

403GIS_TIER_REQUIRED

The tool needs a higher tier than the owner now has (spatial join and zonal statistics need Pro).

409TOOL_API_BINDING_MISSING

A data item the API is bound to is gone, is no longer the owner's, or has no clean version.

413TOOL_API_INPUT_TOO_LARGE

The input has more than 10,000 features.

413TOOL_API_RESULT_TOO_LARGE

The result is too large to answer in one call. Send fewer features.

429API_KEY_QUOTA

The owner is a person who has used the day's API requests their plan allows, which their personal API keys share.

429ENTERPRISE_API_DAILY_LIMIT

The owner is an enterprise that has used its tier's API requests for the day.

429TOOL_API_RATE_LIMITED

More than 60 calls in a minute to this Tool API. Wait a minute and try again.

The errors page has the full code catalogue and a retry policy for each kind of failure.

Errors, limits and quotas

curl -X POST "https://haiyz.net/api/tool-apis/$TOOL_API_ID/run" \ -H "Authorization: Bearer $TOOL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"input":{"type":"Point","coordinates":[46.7,24.7]}}'

{ "ok": true, "statusCode": 200, "code": "TOOL_API_RESULT", "data": { "passed": true, "counts": { "inside": 1, "partial": 0, "outside": 0, "passed": 1 }, "results": [ { "index": 0, "relation": "inside", "percentInside": 100, "pass": true, "matchCount": 1, "reference": { "name": "Saudi Arabia" } } ] } }