openapi: 3.0.0
info:
  title: Geometry Operations API
  description: |
    The Geoapify Geometry Operations API provides powerful spatial analysis and geometry manipulation capabilities.
    It allows you to perform various operations on GeoJSON geometries including boolean operations, measurements,
    transformations, clustering, and more.
    
    The API accepts GeoJSON geometries directly in the request body and returns results in a unified format.
  version: 1.0.0
  contact:
    name: Geoapify
    url: https://geoapify.com
    email: info@geoapify.com
  license:
    name: MIT
    url: https://opensource.org/license/mit
servers:
  - url: https://api.geoapify.com/v1
    description: Primary Geoapify API endpoint

tags:
  - name: Geometry Operations
    description: Perform spatial operations on GeoJSON geometries

paths:
  /geometry/operation:
    post:
      tags:
        - Geometry Operations
      summary: Perform geometry operations on GeoJSON data
      description: |
        Execute various spatial operations on GeoJSON geometries. The operation type determines
        which input fields are required in the request body.
        
        ## Operation Categories
        
        ### 1. Constructive / Polygon Set Operations
        - `union`: Merge multiple polygons into one
        - `intersection`: Find the overlapping area of polygons
        - `difference`: Subtract one polygon from another
        
        ### 2. Point Set / Surface / Clustering
        - `voronoi`: Create Voronoi diagram from points
        - `clustersDbscan`: DBSCAN clustering algorithm
        - `clustersKmeans`: K-means clustering algorithm
        - `concave`: Create concave hull around points (requires maxEdge param)
        - `convex`: Create convex hull around points
        - `tin`: Triangulated irregular network
        
        ### 3. Spatial Predicates (Boolean)
        - `contains`: Check if geometry1 contains geometry2
        - `crosses`: Check if geometries cross
        - `disjoint`: Check if geometries are disjoint
        - `intersects`: Check if geometries intersect
        - `within`: Check if geometry1 is within geometry2
        - `valid`: Check if geometry is valid
        
        ### 4. Measurement (Numeric)
        - `distance`: Calculate distance between two points
        - `area`: Calculate area of a polygon
        - `pointToLineDistance`: Distance from point to line
        - `pointToPolygonDistance`: Distance from point to polygon
        
        ### 5. Line Operations
        - `pointOnLine`: Check if point is on line (boolean)
        - `nearestPointOnLine`: Find nearest point on line
        - `lineIntersect`: Find intersection of two lines
        - `along`: Get point at distance along line
        
        ### 6. Transformations
        - `buffer`: Create buffer around geometry
        - `simplify`: Simplify geometry
        - `transformRotate`: Rotate geometry
        - `transformScale`: Scale geometry
        - `transformTranslate`: Translate geometry
        
        ### 7. Geometry Centers
        - `center`: Calculate center of geometry
        - `centerMean`: Calculate mean center
        - `centerMedian`: Calculate median center
        - `centerOfMass`: Calculate center of mass
        
        ### 8. Bounding / Envelope
        - `bbox`: Get bounding box of geometry
        - `envelope`: Get envelope of geometries
        
        ### 9. Grid & Random Generators
        - `grid`: Generate grid within bbox
        - `randomPoint`: Generate random points
        - `randomLineString`: Generate random line strings
        - `randomPolygon`: Generate random polygons
        
        ### 10. Geometry Queries & Advanced
        - `pointsWithinPolygon`: Find points within polygon
        - `greatCircle`: Calculate great circle arc
        - `tesselate`: Tesselate polygon into triangles
      operationId: geometryOperation
      parameters:
        - name: apiKey
          in: query
          required: true
          description: Your Geoapify API key for authentication
          schema:
            type: string
            example: "YOUR_API_KEY"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeometryOperationRequest'
            examples:
              union:
                summary: Union of two polygons
                value:
                  operation: union
                  polygons:
                    - type: Polygon
                      coordinates: [[[0, 0], [10, 0], [10, 10], [0, 10], [0, 0]]]
                    - type: Polygon
                      coordinates: [[[5, 5], [15, 5], [15, 15], [5, 15], [5, 5]]]
              distance:
                summary: Distance between two points
                value:
                  operation: distance
                  point1:
                    type: Point
                    coordinates: [2.35, 48.85]
                  point2:
                    type: Point
                    coordinates: [2.36, 48.86]
                  params:
                    units: meters
              buffer:
                summary: Buffer around a geometry
                value:
                  operation: buffer
                  geometry:
                    type: LineString
                    coordinates: [[0, 0], [10, 10]]
                  distance: 1000
                  params:
                    units: meters
              pointsWithinPolygon:
                summary: Find points within a polygon
                value:
                  operation: pointsWithinPolygon
                  points:
                    - type: Point
                      coordinates: [5, 5]
                    - type: Point
                      coordinates: [15, 15]
                  polygon:
                    type: Polygon
                    coordinates: [[[0, 0], [10, 0], [10, 10], [0, 10], [0, 0]]]
              area:
                summary: Calculate polygon area
                value:
                  operation: area
                  polygon:
                    type: Polygon
                    coordinates: [[[0, 0], [10, 0], [10, 10], [0, 10], [0, 0]]]
              valid:
                summary: Validate geometry
                value:
                  operation: valid
                  geometry:
                    type: Polygon
                    coordinates: [[[0, 0], [10, 0], [10, 10], [0, 10], [0, 0]]]
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeometryOperationResponse'
              examples:
                geojsonResult:
                  summary: GeoJSON result (union, buffer, etc.)
                  value:
                    type: geojson
                    data:
                      type: Polygon
                      coordinates: [[[0, 0], [10, 0], [15, 5], [15, 15], [5, 15], [0, 10], [0, 0]]]
                numberResult:
                  summary: Numeric result (distance, area)
                  value:
                    type: number
                    data: 1234.56
                booleanResult:
                  summary: Boolean result (valid, contains, etc.)
                  value:
                    type: boolean
                    data: true
                emptyResult:
                  summary: Empty result
                  value:
                    type: empty
                    data: null
        '400':
          description: Bad Request - Invalid input parameters or geometry
        '401':
          description: Unauthorized - Invalid or missing API key
        '429':
          description: Too Many Requests - Rate limit exceeded
        '500':
          description: Internal Server Error

components:
  schemas:
    GeometryOperationRequest:
      type: object
      required:
        - operation
      properties:
        operation:
          type: string
          description: The geometry operation to perform
          enum:
            - intersection
            - difference
            - union
            - voronoi
            - contains
            - crosses
            - disjoint
            - intersects
            - pointOnLine
            - valid
            - within
            - along
            - area
            - bbox
            - buffer
            - center
            - centerMean
            - centerMedian
            - centerOfMass
            - clustersDbscan
            - clustersKmeans
            - concave
            - convex
            - distance
            - envelope
            - greatCircle
            - grid
            - randomPoint
            - randomLineString
            - randomPolygon
            - lineIntersect
            - nearestPointOnLine
            - pointsWithinPolygon
            - pointToLineDistance
            - pointToPolygonDistance
            - tin
            - tesselate
            - simplify
            - transformRotate
            - transformScale
            - transformTranslate
        polygons:
          type: array
          description: Array of polygons (required for union, intersection, difference)
          minItems: 2
          maxItems: 100
          items:
            $ref: '#/components/schemas/PolygonGeometry'
        points:
          type: array
          description: Array of points (required for voronoi, clustering, convex, concave, tin, pointsWithinPolygon)
          minItems: 1
          maxItems: 1000
          items:
            $ref: '#/components/schemas/PointGeometry'
        geometry:
          $ref: '#/components/schemas/AnyGeometry'
        geometry1:
          $ref: '#/components/schemas/AnyGeometry'
        geometry2:
          $ref: '#/components/schemas/AnyGeometry'
        geometries:
          type: array
          description: Array of geometries (required for envelope)
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/AnyGeometry'
        point:
          $ref: '#/components/schemas/PointGeometry'
        point1:
          $ref: '#/components/schemas/PointGeometry'
        point2:
          $ref: '#/components/schemas/PointGeometry'
        line:
          $ref: '#/components/schemas/LineGeometry'
        line1:
          $ref: '#/components/schemas/LineGeometry'
        line2:
          $ref: '#/components/schemas/LineGeometry'
        polygon:
          $ref: '#/components/schemas/PolygonGeometry'
        bbox:
          $ref: '#/components/schemas/BoundingBox'
        distance:
          type: number
          description: Distance value (required for along, buffer, transformTranslate)
        maxDistance:
          type: number
          description: Maximum distance (required for clustersDbscan)
        angle:
          type: number
          description: Rotation angle in degrees (required for transformRotate)
        factor:
          type: number
          description: Scale factor (required for transformScale)
        direction:
          type: number
          description: Direction in degrees (required for transformTranslate)
        type:
          type: string
          description: Grid type (required for grid operation)
          enum:
            - hex
            - point
            - square
            - triangle
        cellSide:
          type: number
          description: Cell side length (required for grid operation)
        count:
          type: integer
          description: Number of random features to generate (required for randomPoint, randomLineString, randomPolygon)
        params:
          $ref: '#/components/schemas/OperationParams'

    GeometryOperationResponse:
      type: object
      required:
        - type
        - data
      properties:
        type:
          type: string
          description: Type of the result
          enum:
            - geojson
            - number
            - boolean
            - empty
        data:
          description: The result data (geometry, number, boolean, or null)
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/AnyGeometry'
            - $ref: '#/components/schemas/FeatureCollection'
            - type: number
            - type: boolean

    PointGeometry:
      type: object
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum: [Point]
        coordinates:
          type: array
          description: "[longitude, latitude]"
          items:
            type: number
          minItems: 2
          maxItems: 2

    LineGeometry:
      type: object
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum: [LineString, MultiLineString]
        coordinates:
          type: array
          description: Array of coordinate pairs or arrays
          items:
            type: array
            items:
              type: number

    PolygonGeometry:
      type: object
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum: [Polygon, MultiPolygon]
        coordinates:
          type: array
          description: Array of linear rings
          items:
            type: array
            items:
              type: array
              items:
                type: number

    AnyGeometry:
      type: object
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - Point
            - LineString
            - Polygon
            - MultiPoint
            - MultiLineString
            - MultiPolygon
        coordinates:
          type: array
          description: Geometry coordinates
          items: {}

    FeatureCollection:
      type: object
      properties:
        type:
          type: string
          enum: [FeatureCollection]
        features:
          type: array
          items:
            $ref: '#/components/schemas/Feature'

    Feature:
      type: object
      properties:
        type:
          type: string
          enum: [Feature]
        geometry:
          $ref: '#/components/schemas/AnyGeometry'
        properties:
          type: object

    BoundingBox:
      oneOf:
        - type: array
          description: "[minLon, minLat, maxLon, maxLat]"
          items:
            type: number
          minItems: 4
          maxItems: 4
        - type: object
          properties:
            lon1:
              type: number
              minimum: -180
              maximum: 180
            lat1:
              type: number
              minimum: -90
              maximum: 90
            lon2:
              type: number
              minimum: -180
              maximum: 180
            lat2:
              type: number
              minimum: -90
              maximum: 90
          required: [lon1, lat1, lon2, lat2]

    OperationParams:
      type: object
      description: Optional parameters that vary by operation
      properties:
        units:
          type: string
          description: Unit of measurement
          enum:
            - meters
            - metres
            - millimeters
            - millimetres
            - centimeters
            - centimetres
            - kilometers
            - kilometres
            - miles
            - nauticalmiles
            - inches
            - yards
            - feet
            - radians
            - degrees
        steps:
          type: integer
          description: Number of steps for buffer operation
        minPoints:
          type: integer
          description: Minimum points for DBSCAN clustering
        numberOfClusters:
          type: integer
          description: Number of clusters for K-means
        maxEdge:
          type: number
          description: Maximum edge length for concave hull (required for concave operation)
        concavity:
          type: number
          description: Concavity for convex hull
        npoints:
          type: integer
          description: Number of points for great circle
        offset:
          type: number
          description: Offset for great circle
        tolerance:
          type: number
          description: Tolerance for simplification
        highQuality:
          type: boolean
          description: High quality simplification
        mutate:
          type: boolean
          description: Whether to mutate the input geometry
        pivot:
          type: array
          description: Pivot point for rotation [lon, lat]
          items:
            type: number
          minItems: 2
          maxItems: 2
        origin:
          description: Origin for scaling
          oneOf:
            - type: string
              enum: [center, centroid, sw, se, nw, ne]
            - type: array
              items:
                type: number
              minItems: 2
              maxItems: 2
        zTranslation:
          type: number
          description: Z-axis translation
        numVertices:
          type: integer
          description: Number of vertices for random geometries
        maxLength:
          type: number
          description: Maximum length for random line strings
        maxRotation:
          type: number
          description: Maximum rotation for random line strings
        maxRadialLength:
          type: number
          description: Maximum radial length for random polygons
        recompute:
          type: boolean
          description: Recompute bounding box

