Paste boring log data as JSON, or open an Excel workbook, to see the log drawn. Download it as SVG or PNG, or print it to PDF. Your data stays in your browser; only the map tiles for a log's location are loaded from OpenStreetMap or Esri.
A boring log is one JSON object. Only layers is required (schema_version is optional; the latest version is assumed). Depths are measured down from the ground surface. Fields set to null are treated as missing. A misspelled field name is reported as an error, so typos don't go unnoticed.
{
"schema_version": "1.0",
"units": { "length": "m", "unit_weight": "kN/m3", "diameter": "mm" },
"metadata": { "boring_name": "B-1", "site_name": "…", "latitude": 34.07, "longitude": -118.44,
"elevation": 120.5, "start_date": "2024-05-01", "boring_type": "Hollow-stem auger",
"rig": "…", "diameter": 200, "hammer": "Automatic", "energy_ratio": 80, "logged_by": "…" },
"groundwater": [ { "depth": 4.2, "date": "2024-05-01", "note": "encountered" } ],
"layers": [
{ "top": 0, "bottom": 3.5, "description": "Brown, loose, moist, silty SAND", "uscs": "SM" }
],
"samples": [
{ "top": 1.5, "bottom": 1.95, "name": "S-1", "type": "SPT", "blow_count": 8,
"specimens": [ { "name": "S-1A", "top": 1.6, "bottom": 1.75, "water_content": 18.2, "fines_content": 24 } ] }
]
}
unitslength: m or ft. unit_weight: kN/m3 or pcf. diameter: mm, cm, m, in or ft. Metric is the default.layers[]top, bottom, description, uscs (e.g. SM or SP-SM), and hatch to choose the graphic log pattern: a USCS symbol, a built-in material such as FILL, ASPHALT, SANDSTONE or GRANITE (all 67 are listed in the Hatches… window), or your own ("none" leaves it blank). Without hatch, a material or rock named as the principal material in the description is drawn, such as fill (also "FILL: silty sand" or "(hydraulic fill)"), asphalt, topsoil, no recovery or shale, ahead of the USCS symbol; otherwise, without uscs, the pattern is guessed from the description, and when the description determines a USCS symbol (e.g. "fat CLAY" or "(SP-SM)"), it is shown in parentheses. A recorded uscs that isn't a possible symbol (such as GW-GP) or that differs from the symbol the description determines (SP-SM on a "well graded SAND") gets a warning, and the symbol read from the description is shown below it in parentheses: SP-SM (SW).samples[]top, bottom, name, type (SPT, ModCal, DamesMoore, Shelby, Piston, Osterberg, Pitcher, Denison, LargeDiameter, Block, DirectPush, GelPush, Sonic, Core, TripleTube, Bulk, Grab, Composite, Auger, Trench, Disturbed, Other, and NoRecovery, which is accepted with a warning and noted as "No recovery" in the remarks; the Hatches… dialog shows each symbol), blow_count (a number, or text such as "50/5in"), blows (per increment, e.g. [6, 8, 10]), energy_ratio, sampler_diameter, recovery_percent, total_unit_weight and dry_unit_weight (of the whole sample), remarks (a sample has remarks, not a description), specimens. recovery_percent is the recovery as a percent of the sample length and is noted in the remarks ("Recovery 80%"); use "recovery_percent": 0 for no recovery and keep the sampler that was tried as type. An older recovery length is converted to a percent, with a warning.samples[].specimens[]name, top, bottom, water_content, total_unit_weight, dry_unit_weight, specific_gravity, fines_content, liquid_limit, plastic_limit, nonplastic, uscs (from the lab classification; shown in the Lab USCS column), remarks. Each is drawn as a box over its depth range in the Specimen column, with its name and results on a row level with it. A specimen without top gets no box and its results are shown level with the sample; with top only, it is drawn at that depth. Lab results put on the sample itself are shown the same way, with a warning (except unit weights, which may be given for a whole sample).groundwater[]depth, date, note.depth_notes[]depth and description: an observation at one depth within a layer, drawn in italics in the material description column.layoutwidth (px), font_size, and columns, the columns in order. Each is a column id or an object with id, a relative width (the columns share the log's width in proportion) and a label. A new id with "source": "sample" or "specimen" shows each sample's or specimen's custom value ("custom": { "pocket_pen": 1.5 }; field names the key if it isn't the id, decimals rounds numbers), and "source": "blank" adds an empty column. You don't need to write this by hand: the Layout… window sets all of it, including the values of custom columns.references[]text and url: the sources of the data (e.g. the report the boring comes from), listed in the header above the log; an http(s) url is a link in the SVG.patterns{ "FILL": { "name": "Fill", "svg": "<svg viewBox='0 0 40 20'><line x1='0' y1='20' x2='40' y2='0' stroke='black'/></svg>" } }, as SVG markup (drawing elements only: path, rect, circle, ellipse, line, polyline, polygon, g), or as a picture: "image": "data:image/png;base64,…" with "width" and "height" in px. Add "kind": "sampler" for a sampler symbol, and tile_width (px) to change the tile size. A USCS code or built-in sampler name replaces the built-in pattern. The Hatches… button builds these entries from an image file and applies them to the layers or samples you pick. They are saved in the JSON, not on the server; to use them with the API, see using your own hatches with the API.The complete definition is in the JSON Schema.
Instead of writing JSON, you can fill in the Excel template and open it with Open files… (or drop it on the editor). One workbook holds one boring; it is converted to the JSON format in the editor, so you can check, edit and download it as usual. The workbook is read in your browser and is not uploaded.
Each sheet is one part of the JSON: Units, Metadata, Layers, Samples, Specimens, Groundwater, Depth notes, References, Layout and Columns. The table sheets have one row per layer, sample and so on, under a header row of field names (the names used in the JSON); the Units, Metadata and Layout sheets have a field name in column A and its value in column B. The rows of explanation above each header row (units, allowed values) can be deleted: the header row is found by its field names. Specimens are put with their sample by the sample name in their sample_name column. Extra columns on the Samples and Specimens sheets become custom values, which the Columns sheet can show. Filled-in examples: B-3-example.xlsx (the coastal example: layers, SPT samples, lab specimens with Atterberg limits and unit weights, groundwater) and NAS-1.xlsx (a real boring from Nantou, Taiwan).
To render from a script or another website, send the JSON (or an AGS4 or DIGGS file) as the body of a POST request to https://uclageo.com/boring-log-viewer/api/render with Content-Type: application/json. The response is the log as SVG (the default), PNG or an HTML page.
curl -X POST -H "Content-Type: application/json" --data-binary @boring.json \
"https://uclageo.com/boring-log-viewer/api/render?format=png&units=ft" -o boring.png
import requests
with open("boring.json") as f:
r = requests.post("https://uclageo.com/boring-log-viewer/api/render",
params={"format": "svg"}, data=f.read(),
headers={"Content-Type": "application/json"})
r.raise_for_status()
open("boring.svg", "w", encoding="utf-8").write(r.text)
formatsvg, png or html. Without it, the Accept header decides, and SVG is the default.units (m or ft), width (px), header, legend, fit_text and hide_empty_columns (true or false), columns (a comma-separated list, e.g. depth,graphic,description,blow_count), title, font_size, height, scale.png_scale (0.5 to 4, default 2), download=true (asks the browser to save the file instead of showing it).{ "error": "…", "errors": [{ "path": "/layers/2/uscs", "message": "…" }] }. Status 400 means malformed JSON or a bad query parameter, 422 an invalid boring log, and 429 more than 60 requests per minute. Warnings, such as gaps between layers, don't stop rendering and are returned in the X-Boring-Log-Warnings header.POST api/validate returns { valid, errors, warnings }. GET api/schema returns the JSON Schema, and GET api/health reports whether the service is up.An AGS4 file can be sent as it is, with Content-Type: text/plain. It is converted to the JSON format (strata, samples, SPT results, water content, Atterberg limits, fines, densities and water strikes) and drawn; add loca_id to choose the borehole when the file has more than one. POST api/ags returns the converted JSON for every borehole instead, for editing or checking. The same conversion runs on this page when you open an .ags file.
DIGGS XML files (2.5, 2.6 and 3.x) work the same way: send one with Content-Type: application/xml to api/render (with loca_id for the borehole name) or to api/diggs for the converted JSON, or open it on this page. Strata come from the lithology observations, samples from the sampling activities, and SPT and laboratory values from the test results. Files may be up to 10 MB.
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
Requests are limited to 1 MB of JSON (10 MB for AGS4 and DIGGS files), 2,000 layers and 5,000 samples. Submitted data is not stored.
Hatches and sampler symbols you make on this page are not stored on the server. They are saved inside the log's JSON, in a section called "patterns": as SVG markup, or, for a hatch kept as a picture, as a long line of encoded text. The API draws a custom hatch only if the JSON you send contains that "patterns" section. To use one from a script:
"patterns" section at the end. For example, a hatch with the code FILL looks like this, with the SVG cut short here:
"patterns": {
"FILL": {
"svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 96 96\" width=\"96\" height=\"96\"><path fill=\"rgb(0,0,0)\" d=\"M 12 4 L 20 4 …\"/></svg>",
"name": "Fill"
}
},
"patterns" section, because the "svg" or "image" line can be long.hatches.json."patterns" section from that file, and set "hatch": "FILL" on each layer that should use it. For a sampler symbol, set a sample's "type" to its code instead. A code that replaces a built-in one, such as SM, needs no "hatch": every layer with that USCS symbol uses it.A script can read the saved file and add its hatches to every log it sends:
import json, requests
hatches = json.load(open("hatches.json"))["patterns"] # the JSON copied from this page
log = json.load(open("boring.json"))
log["patterns"] = hatches
log["layers"][0]["hatch"] = "FILL" # 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()
open("boring.svg", "w", encoding="utf-8").write(r.text)
You can also write a simple hatch by hand. This one draws diagonal lines, one tile 40 × 20 px (the tile's size comes from its viewBox); single quotes inside the SVG save escaping them in JSON:
"patterns": {
"SLOPE": {
"name": "Sloping lines",
"svg": "<svg viewBox='0 0 40 20'><line x1='0' y1='20' x2='40' y2='0' stroke='black' stroke-width='1.5'/></svg>"
}
}
Only drawing elements (path, rect, circle, ellipse, line, polyline, polygon, g) and fill and stroke attributes are kept; titles and editor metadata (from Inkscape or Illustrator) are dropped, and anything else, such as text, embedded images, <style> or scripts, is rejected with a message saying what to change.
If a layer uses a code that isn't defined in "patterns", the API returns a 422 error naming the layer and the code. To reuse a hatch in another log on this page, paste the "patterns" section into that log's JSON, or add the image again with the Hatches… window.