AGS download service

This is a high-level summary of the BGS AGS download service, which provides free and open access to AGS geotechnical data held by the BGS. AGS data is the industry-standard exchange format for geotechnical data in the UK.

This service will be further developed in the coming months and years to deliver greater functionality.

For more information, visit the official website for the Association of Geotechnical and Geoenvironmental Specialists to learn more about the AGS and the technical details of the data exchange format.

High-level workflow

High-level workflow diagram
  • AGS (and associated) files are donated to the BGS and are stored in their original form, accessible at the detailed accession search.
  • Subject to donors' consent to data being made available, AGS data is extracted into a relational database. As part of this process, the BGS generate new PROJ and LOCA IDs, which are unique across all projects.
  • The locations of each borehole (or LOCA) are then exposed via a public web map service (WMS) as well as an ESRI REST API service. Using these services, the public can identify the boreholes they wish to download.
  • When the BGS AGS exporter web service is given a list of borehole identifiers (LOCA_IDs) a request is made to the database and a download is prepared.
  • If a group of boreholes of different origin are selected, one AGS file is generated for each originating project. This file contains a subset of the original data as described below. The original project and borehole IDs are replaced with the unique values generated by the BGS.

What does each BGS-generated AGS file contain?

All files are provided in version 4 of the AGS standard, regardless of the original version of the files donated.

The service is borehole and not project focused.

  • End users request data for a list of boreholes using a BGS-generated, globally unique ID, which we internally refer to as BGS_LOCA_ID but appears as LOCA_ID in the generated file.
  • The export will contain one or more AGS files, one per original project.
  • Each project file will only contain LOCA values for the boreholes requested.

Below is a description of the groups that are included in version 1 of this service, displayed in the order that they appear in the files.

Group: PROJ

Heading Description Example
PROJ_ID BGS-generated unique ID containing the date of donation and incrementing number. Original value moved to LOCA. LOCA_ORJO. 20160209172248
FILE_FSET Hard-coded reference to the BGS metadata file supplied with all downloads. Original values removed. BGSFileSet01

The rest of the group remains as defined in the original donated file.

Group: UNIT

Contains all the values from the original donated file plus a row for the following entry (which happens to be used in the TRAN_DATE attribute):

Unit type = "DATA"; unit code = "yyyy-mm-dd", and unit description = "year month day"

Group: TYPE

Contains all the values from any original donated file, i.e. the contents of this group are not project specific.

Group: TRAN

Heading Description Example
TRAN_ISNO Hard coded value of 1. 1
TRAN_DATE Date that the download was requested in yyyy-mm-dd format. 2017-04-10

The rest of the group is self-explanatory.

Any TRAN data associated with the original donation is excluded from this download. Refer to the original donation for such legacy information.

Group: FILE

All files associated with the original donation are excluded from this download and therefore excluded from the FILE group. The only entry refers to the BGS metadata text file.

Group: DICT

Contains all the values from the original donated file (as long as the descriptions were provided) plus three custom fields. These were accepted as part of the AGS 4 standard (4.0.4) but may not be recognized by some validation tools, so are included as custom fields for completeness.

  • LOCA_ORID = archive original hole ID
  • LOCA_ORJO = archive original job reference
  • LOCA_ORCO = archive original company

Group: ABBR

Please note: The AGS 3.1 group CODE logically maps to the AGS4 concept of ABBR, however, due to the lack of description in CODE we do not migrate those values into ABBR. This is something we may change in the next version of the AGS exporter.

All entries containing HEADING "HOLE_***" are converted to "LOCA_***"

The following entries have been hardcoded:

  • "DATA", "FILE_DOCT", "REP", "Report", "AGS4", ""
  • "DATA", "FILE_TYPE", "TXT", "Plain text document format", "-",""

Group: LOCA

Heading Description Example
LOCA_ID BGS-generated unique ID containing the PROJ_ID and an incrementing number. Original value moved to LOCA. LOCA_ORID. 20160209172248_101
LOCA_ORID Original LOCA_ID (or HOLE_ID if from a pre-AGS 4 file) BH1
LOCA_ORJO Original PROJ_ID ACME Project 1
LOCA_ORCO Original company name ACME

Rest of group remains as it was supplied in the original donation.

Group: GEOL

Heading Description Example
LOCA_ID Updated to use the BGS unique value 20160209172248_101

Rest of group remains as it was supplied in the original donation.