# Polygon Geometry API
> Computational geometry for arbitrary polygons and point sets — on a plane, with no map or shape templates needed. The area endpoint takes a polygon as a list of [x,y] vertices and returns its area (by the shoelace formula), perimeter, centroid, winding orientation (clockwise or counter-clockwise), whether it is convex, and its bounding box. The contains endpoint tests whether a point is inside a polygon, outside it, or exactly on its boundary, using robust ray casting that handles concave shapes correctly. The convex-hull endpoint computes the convex hull of a set of points by Andrew's monotone chain, along with its area and perimeter. It works for any simple polygon, convex or concave. Everything is computed locally and deterministically, so it is instant and private. Ideal for graphics and game development, GIS and mapping, CAD and collision detection, computational geometry, and data visualisation. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 4 endpoints. This is planar polygon geometry; for the area of named shapes (circle, triangle, …) use a geometry API and for geographic GeoJSON area on the earth use a GeoJSON API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/polygon-api/..."
```

## Pricing
- **Free** (Free) — 8,135 calls/Mo, 2 req/s
- **Starter** ($10/Mo) — 17,650 calls/Mo, 8 req/s
- **Pro** ($30/Mo) — 227,500 calls/Mo, 20 req/s
- **Mega** ($68/Mo) — 1,180,000 calls/Mo, 50 req/s

## Endpoints

### Polygon

#### `GET /v1/area` — Polygon area, centroid & properties

**Parameters:**
- `polygon` (query, required, string) — Vertices [[x,y],...] Example: `[[0,0],[4,0],[4,4],[0,4]]`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/polygon-api/v1/area?polygon=%5B%5B0%2C0%5D%2C%5B4%2C0%5D%2C%5B4%2C4%5D%2C%5B0%2C4%5D%5D"
```

**Response:**
```json
{
    "data": {
        "area": 16,
        "convex": true,
        "centroid": [
            2,
            2
        ],
        "vertices": 4,
        "perimeter": 16,
        "orientation": "counter-clockwise",
        "signed_area": 16,
        "bounding_box": {
            "max_x": 4,
            "max_y": 4,
            "min_x": 0,
            "min_y": 0,
            "width": 4,
            "height": 4
        }
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:05.342Z",
        "request_id": "9a83ac9c-56fc-4467-8eea-3afc34a473bf"
    },
    "status": "ok",
    "message": "Polygon area",
    "success": true
}
```

#### `GET /v1/contains` — Point in polygon test

**Parameters:**
- `polygon` (query, required, string) — Vertices [[x,y],...] Example: `[[0,0],[4,0],[4,4],[0,4]]`
- `point` (query, optional, string) — [x,y] Example: `[2,2]`
- `x` (query, optional, string) — or x
- `y` (query, optional, string) — and y

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/polygon-api/v1/contains?polygon=%5B%5B0%2C0%5D%2C%5B4%2C0%5D%2C%5B4%2C4%5D%2C%5B0%2C4%5D%5D&point=%5B2%2C2%5D"
```

**Response:**
```json
{
    "data": {
        "point": [
            2,
            2
        ],
        "inside": true,
        "position": "inside",
        "on_boundary": false,
        "polygon_vertices": 4
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:05.437Z",
        "request_id": "72ef7714-1f0b-47de-b0ef-3a49e72f5945"
    },
    "status": "ok",
    "message": "Point in polygon",
    "success": true
}
```

#### `GET /v1/convex-hull` — Convex hull of points

**Parameters:**
- `points` (query, required, string) — Points [[x,y],...] Example: `[[0,0],[4,0],[4,4],[0,4],[2,2]]`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/polygon-api/v1/convex-hull?points=%5B%5B0%2C0%5D%2C%5B4%2C0%5D%2C%5B4%2C4%5D%2C%5B0%2C4%5D%2C%5B2%2C2%5D%5D"
```

**Response:**
```json
{
    "data": {
        "area": 16,
        "hull": [
            [
                0,
                0
            ],
            [
                4,
                0
            ],
            [
                4,
                4
            ],
            [
                0,
                4
            ]
        ],
        "perimeter": 16,
        "hull_points": 4,
        "input_points": 5
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:05.538Z",
        "request_id": "22d73884-6772-4af1-bda3-841afd06b48a"
    },
    "status": "ok",
    "message": "Convex hull",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/polygon-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "name": "Polygon Geometry API",
        "notes": "Planar cartesian coordinates. Shoelace area, ray-casting point-in-polygon, monotone-chain hull. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/area",
                "params": {
                    "polygon": "[[x,y],…] vertices"
                },
                "returns": "area, perimeter, centroid, orientation, convexity, bounding box"
            },
            {
                "path": "/v1/contains",
                "params": {
                    "point": "[x,y] (or x and y)",
                    "polygon": "[[x,y],…]"
                },
                "returns": "inside / outside / boundary"
            },
            {
                "path": "/v1/convex-hull",
                "params": {
                    "points": "[[x,y],…]"
                },
                "returns": "the convex hull and its area/perimeter"
            },
            {
                "path": "/v1/meta",
                "params": [],
                "returns": "this document"
            }
        ],
        "description": "Computational geometry for arbitrary polygons and point sets — on a plane, with no map or shape templates needed. The area endpoint takes a polygon as a list of [x,y] vertices and returns its area (by the shoelace formula), perimeter, centroid, winding orientation (clockwise or counter-clockwise), whether it is convex, and its
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/polygon-api
OpenAPI spec: https://www.oanor.com/api/polygon-api/openapi.json