Boring Log Viewer docs

Render API

Send boring log data from a script and get the drawn log back as SVG, PNG or a web page. Useful for drawing many logs at once, or showing logs on your own website.

The basics

Send the boring log JSON in a POST request to:

https://uclageo.com/boring-log-viewer/api/render

with the header Content-Type: application/json. The reply is the drawn log. Add options to the address after a ?, for example ?format=png&units=ft.

The data you send isn't stored or logged. The API needs no account or key.

From Python

Using the requests package (pip install requests):

import requests

API = "https://uclageo.com/boring-log-viewer/api/render"

with open("B-1.json", encoding="utf-8") as f:
    log = f.read()

r = requests.post(API, params={"format": "png", "units": "ft"}, data=log.encode("utf-8"),
                  headers={"Content-Type": "application/json"})
r.raise_for_status()
with open("B-1.png", "wb") as f:
    f.write(r.content)

Drawing a whole folder of borings

import pathlib, requests

API = "https://uclageo.com/boring-log-viewer/api/render"

for path in sorted(pathlib.Path("borings").glob("*.json")):
    r = requests.post(API, params={"format": "svg", "width": 900},
                      data=path.read_bytes(), headers={"Content-Type": "application/json"})
    if r.ok:
        path.with_suffix(".svg").write_text(r.text, encoding="utf-8")
        print("drew", path.name)
    else:
        # The reply says what's wrong, e.g. {"error": ..., "errors": [{"path": "/layers/2/uscs", ...}]}
        print(path.name, "failed:", r.json())

Building the log in Python

If your data is already in Python (from a database or a spreadsheet), build the log as a dictionary and send it with json=:

log = {
    "schema_version": "1.0",
    "units": {"length": "ft"},
    "metadata": {"boring_name": "B-1"},
    "layers": [
        {"top": 0, "bottom": 4, "description": "Brown silty SAND", "uscs": "SM"},
        {"top": 4, "bottom": 20, "description": "Gray lean CLAY", "uscs": "CL"},
    ],
}
r = requests.post(API, params={"format": "svg"}, json=log)

Python's None becomes JSON null, which the viewer treats as "not given", so missing values from a database can be passed straight through.

From the command line

curl -X POST -H "Content-Type: application/json" --data-binary @B-1.json \
     "https://uclageo.com/boring-log-viewer/api/render?format=png&units=ft" -o B-1.png

On Windows PowerShell, use curl.exe rather than curl, and put the command on one line.

On a web page

The API can be called from any website. To show a log on a page:

const r = await fetch('https://uclageo.com/boring-log-viewer/api/render?format=svg', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(log),
});
document.getElementById('log').innerHTML = await r.text();

A page on another website can't read the X-Boring-Log-Warnings header (the server doesn't expose it to browsers). To get the warnings in a browser, call api/validate as well.

A JavaScript application can also draw logs itself, with no server: see JavaScript in your own page, which has a complete example application.

Parameters

ParameterValuesMeaning
formatsvg, png, htmlWhat to send back. Default SVG (or whatever the request's Accept header asks for).
png_scale0.5 to 4Resolution of a PNG, as a multiple of the SVG size. Default 2.
downloadtrueAsk a browser to save the file rather than show it
units, unit_weight, diameter_unitssee Display optionsDisplay units
width, height, scale, font_sizenumbersSize
header, legend, references, fit_text, hide_empty_columns, infer_uscs, infer_materialstrue/falseTurn parts of the drawing on or off
columnscomma-separated liste.g. depth,graphic,description,blow_count. Can include the custom columns of the log's layout.
titletextTitle
loca_idborehole nameFor AGS4 and DIGGS files with several boreholes: which one to draw
id_prefixa letter, then letters, digits, _ or -Prefix for the ids inside the SVG, needed when several logs share one web page

An unknown or misspelled parameter is an error, so a typo doesn't silently go unused. Parameters take precedence over the log's own layout.

Sending AGS4 and DIGGS files

An AGS4 file can be sent as it is with Content-Type: text/plain, and a DIGGS file with Content-Type: application/xml (application/x-ags, text/csv and text/xml are also accepted). Add loca_id to pick the borehole when the file has more than one.

Excel workbooks can't be sent to the API (the reply is a 415 error). Open them on the viewer page instead, or convert them there and send the JSON.

curl -X POST -H "Content-Type: text/plain" --data-binary @site.ags \
     "https://uclageo.com/boring-log-viewer/api/render?loca_id=BH01&format=png" -o BH01.png

To get the converted JSON instead of a drawing (to check or edit it, or to see the borehole names), send the file to api/ags or api/diggs. The reply lists every borehole:

{ "documents": [ { "loca_id": "BH01", "document": { ...boring log JSON... } }, ... ],
  "warnings": [ ... ] }

Using your own hatches with the API

Hatches made on the web page are saved in the log's JSON, in the "patterns" section, not on the server. To use them from a script, include that section in the JSON you send:

  1. On the web page, add your hatch with Hatches… (see Your own hatches).
  2. Click Format, select all the JSON (Ctrl+A) and copy it into a text file, e.g. hatches.json.
  3. In your script, copy its patterns into each log, and set hatch on the layers that use it:
import json, requests

hatches = json.load(open("hatches.json", encoding="utf-8"))["patterns"]

log = json.load(open("B-1.json", encoding="utf-8"))
log["patterns"] = hatches
log["layers"][0]["hatch"] = "FILL_CALTRANS"     # the layers that use the hatch

r = requests.post("https://uclageo.com/boring-log-viewer/api/render",
                  params={"format": "svg"}, json=log)
r.raise_for_status()

A hatch that replaces a built-in code, such as SM or SPT, needs no hatch or type: it's used automatically.

Errors and warnings

When something is wrong, the reply has an error status and a JSON body that says what and where:

{ "error": "Invalid boring log",
  "errors": [ { "path": "/layers/2/uscs", "message": "is not a recognized USCS symbol (e.g. SM, CL, SP-SM)" } ] }

The path points into your data: /layers/2/uscs is the uscs of the third layer (counting starts at 0).

StatusMeans
400The JSON can't be read (with the position of the problem), or a parameter is wrong; a text or XML body that is neither AGS4 nor DIGGS
406Unknown format (on api/render)
413Too large: over 1 MB of JSON, or 10 MB for an AGS4 or DIGGS file
415Wrong Content-Type
422The data is readable but not a valid boring log; more than 2,000 layers or 5,000 samples; a PNG over 40 megapixels; or an AGS4/DIGGS file that can't be used (AGS3, no boreholes, no borehole chosen from several)
429Too many requests: the limit is 60 per minute. Wait a minute, or add a short pause between requests in a loop. This reply has a different body: { "statusCode": 429, "error": ..., "message": ... }, with no errors list.

Warnings, such as a gap between two layers, don't stop the drawing. They're sent in the X-Boring-Log-Warnings response header.

Other endpoints

EndpointReturns
POST api/validateChecks a log without drawing it: { "valid": ..., "errors": [...], "warnings": [...] }
POST api/ags, POST api/diggsA file converted to boring log JSON, one per borehole
GET api/schemaThe JSON Schema
GET api/healthWhether the service is up, and its version