Concepts

After you have reviewed the steps to Get Started with GEOSPAN, review the following topics to become familiar with geospatial and geoprocessing topics within the GEOSPAN ecosystem.

Well-Known-Text (WKT)

What is WKT?

WKT is a simplified geometry encoding that is quick to parse and emit. The Wikipedia page for WKT has a nice write-up and examples of the format in use.

Why not GeoJSON?

GeoJSON is great! But there are some advantages that WKT can provide:

  • Typing for WKT is much simpler. GeoJSON is an object-type with very specific property values and sub-objects. While this can be done it requires additional overhead and the type (object) on initial glance is not descriptive. WKT is a string. The input property is named wkt in GEOSPAN APIs to provide consistency and clarity that this is a WKT-String and those familiar with common GIS geometry-types will recognize it immediately.
  • WKT parsing can be deferred. When embedding a GeoJSON object into a request body, the entire body of the request, including the GeoJSON will be parsed by most frameworks. If an API does not actually need the geometry information this can slow down request parsing especially as the GeoJSON grows larger in size.

Helpful utilities for WKT

WGS84 Decimal Degrees

GEOSPAN APIs expect incoming geometries to use WGS84 Decimal Degrees. This is the same as the GeoJSON specification.

gSquare Lifecycle

Estimates are generated asynchronously. A request is made to create an estimate, a query key is returned, and then the query should be monitored for success or failure.

flowchart LR
    A[Call /estimate/] -->|Get queryKey| B(Poll /query/:queryKey)
    B --> C{Check status}
    C -->|PENDING| C
    C -->|FAILURE| E[Report error]
    C -->|SUCCESS| F[Read results]

gPro Lifecycle

Requests for the gPro API go through a multi-stage lifecycle. A new request can either enter the “Pre-Model” stage or be immediately canceled. From “Pre-Model”, the request moves to “Ready” and then “Modeling”. During “Modeling”, the request goes through a series of QA steps, during which the request can be progressed, rejected, or canceled. The final outcome is either the request being completed or rejected.

flowchart TD
   A[New] --> B[Pre-Model]
   A[New] --> N((Canceled))
   B[Pre-Model] --> C[Ready]
   B[Pre-Model] --> N((Canceled))
   C[Ready] --> D[Modeling]
   D[Modeling] --> E[QA1]
   E[QA1] --> F[QA1 In Process]
   E[QA1] --> I[Rejected]
   E[QA1] --> N((Canceled))
   F[QA1 In Process] --> G[QA2]
   F[QA1 In Process] --> I[Rejected]
   F[QA1 In Process] --> N((Canceled))
   G[QA2] --> H[QA2 In Process]
   G[QA2] --> J[Failed QA]
   G[QA2] --> I[Rejected]
   H[QA2 In Process] ----> L((Completed))
   H[QA2 In Process] --> J[Failed QA]
   H[QA2 In Process] --> N((Canceled))
   H[QA2 In Process] --> G[QA2]
   I[Rejected] --> D[Modeling]
   I[Rejected] --> N((Canceled))
   J[Failed QA] --> F[QA1 In Process]
   J[Failed QA] --> I[Rejected]
   J[Failed QA] --> N((Canceled))

style L fill:#6fac5d
style N fill:#b94663
style F fill:#bc7d39
style H fill:#bc7d39
style D fill:#bc7d39
style B fill:#bc7d39