Basic API operations#

The GeoDataHub Web API is based on REST principles. Readers not familiar with REST APIs are encouraged to understand the basics before reading on.

Data resources are accessed via standard HTTP requests. Where possible, the web API uses appropriate HTTP verbs for each action.

Method	Action
GET	Retrieves resources
POST	Creates resources
PUT	Changes and/or replaces resources
DELETE	Deletes resources

The API is split into operations on different resources. Operations specific to datasets use the URI https://api-dev.geodatahub.dk/datasets/. Depending on the HTTP method the same URI can get, add, change, or remove datasets. See the examples section for more.

Global data model#

Each dataset contains a fixed set of metadata attributes defined by the platform and a variable set of metadata defined by the schema. The schema specific parameters are stored under the distribution_info key while all other parameters exists for all datasets,

{
  "identifier": "6376f381-09f0-4dbe-a994-a88a4847defe",
  "owner": "aa59467e-9aef-4854-a762-920fe20a9747",
  "organization": "00000000-0000-0000-0000-000000000000",
  "datatype": "https://schemas.geodatahub.dk/organizations/geus/geophysics/wenner.json",
  "citation": "",
  "description": "Odense Syd, historiske Wenner data",
  "larger_work": "",
  "distribution_info": {
    "Ident": "dk.mim.ode.wenner-odensesyd.Lindved_WEN_3",
    "Project": "Odense Syd, historiske Wenner data",
    "Purpose": "saarbarhed",
    "Contractor": "COWI A/S",
    "Dataset Id": 700849,
    "Project Id": 1508,
    "Maximum RHoa": 57.0,
    "Minimum RHoa": 46.0,
    "Inserted Date": "2009-01-09",
    "Project Ident": "dk.mim.ode.wenner-odensesyd",
    "Maximum A-distance": 25.0,
    "Minimum A-distance": 25.0,
    "Maximum Focus Depth": 12.976,
    "Minimum Focus Depth": 12.976,
    "Number Of Positions": 24
  },
  "result": {
    "download_link": "http://gerda.geus.dk/Gerda/dataset/show/700849"
  },
  "projected_geometry": {
    "type": "LineString",
    "coordinates": [
      [
        10.398255,
        55.329524
      ],
      [
        10.404169,
        55.33369
      ]
    ]
  }
}

The platform specific attributes are defined in the API reference. For convenience the most important are listed below,

Parameter	Definition
`identifier`	Random unique identifier following the uuid v4 format (ex. `6376f381-09f0-4dbe-a994-a88a4847defe`)
`result`	JSON encoded list with information linking the metadata information with one or more files
`projected_geometry`	The 2D geometry, in GeoJSON format, of the dataset (`POINT`, `LINE`, or `POLYGON`)
`datatype`	The full schema URI that defines the `distribution_info` section
`distribution_info`	Dataset specific metadata attributes

The variable names are based on the INSPIRE Geoph Measurement class.

The result section#

Note

The result document and backend logic is still under development and is not considered stable.

Metadata is linked to the actual files or data streams containing the data through the result parameter. The file information is encoded as JSON allowing flexibility in the possible parameters to include. The result parameter must include the following attributes,

uri: Local or remote path to the file or data stream
protocol: The protocol used to access the data (e.g. HTTP, FTP, FILE, etc)
file extension: The file extension (e.g. pdf, las etc.)
source: The software or instrument used to generate, process or transform the data

Possible additional attributes are,

md5: A md5 hash sum of the file content
license: URL to the terms of use for public or commercial data

Example of the result parameter,

[{
  "uri": "https://txdata.usgs.gov/GeoLogArchiver/odata/Logs(1618)/LogFile",
  "location": "HTTPS",
  "file extension": "las",
  "source": "unknown",
  "md5": "060b49d83ba4ea60aefcde8885bad26c"
}]

Example requests#

Description	HTTP Method	Request format
Get a specific Dataset with ID `6376f381-09f0-4dbe-a994-a88a4847defe`	GET	https://api-dev.geodatahub.dk/datasets/6376f381-09f0-4dbe-a994-a88a4847defe
Add a new dataset (See required payload)	POST	https://api-dev.geodatahub.dk/datasets
Get all datasets with schema `https://schemas.geodatahub.dk/organizations/usgs/geophysics/geolog.json`	GET	`https://api-dev.geodatahub.dk/datasets?q={"https://schemas.geodatahub.dk/organizations/usgs/geophysics/geolog.json": ""}`
Get all Geolog datasets starting below 10 ft	GET	`https://api-dev.geodatahub.dk/datasets?q={"https://schemas.geodatahub.dk/organizations/usgs/geophysics/geolog.json":{"DepthStartFt": {"$gt": 10}}}`
Get all data within a polygon	GET	`https://api-dev.geodatahub.dk/datasets?q={"geometry":{\"$contains\":\"POLYGON((7.9 55.4,8.1 55.4,8.1 55.6,7.9 55.6,7.9 55.4))\"}}`

Search format#

GeoDataHub supports three modes of search,

Metadata search: Find all datasets with a specific metadata attribute
Datatype search: Find all datasets of a specific datatype
Geography search: Find all datasets within a geographic area

Users can freely combine different modes depending on their needs.

A dataset search encodes the query as a JSON formatted parameter in the URL. All search requests are sent to the https://api-dev.geodatahub.dk/datasets URL with the query encoded as q (e.g. https://api-dev.geodatahub.dk/datasets?q="YOUR QUERY").

The search either contains a schema or geometry at the top-level. To search for all Geolog data send the following query,

{
"https://schemas.geodatahub.dk/organizations/usgs/geophysics/geolog.json": ""
}

The URL for this query is,

GET https://api-dev.geodatahub.dk/datasets?q={"https://schemas.geodatahub.dk/organizations/usgs/geophysics/geolog.json": ""}

HEADERS
  "Authorization": "NgCXRK...MzYjw"

The empty value indicates no filtering is needed beyond the schema. A search for all Geolog data within Florida is,

{
"https://schemas.geodatahub.dk/organizations/usgs/geophysics/geolog.json":
    {
    "StateName": "Florida"
    }
}

StateName is defined in the Geolog schema.

Currently, the query language supports two simple logical operators ($lt less than and $gt greater than). To filter to only logs in Florida that are also deeper than 90 ft,

{
"https://schemas.geodatahub.dk/organizations/usgs/geophysics/geolog.json": {
    "StateName": "Florida",
    "DepthEndFt": {"$gt": 90}
}
}

Query parameters are additive so both conditions are required on the dataset. The logical OR operation (i.e. one or the other) is currently not supported.

Searching within a geographic region is supported using the top-level geometry parameters. The geometry is defined by a polygon encoded as Well known text.

{
"geometry": {
    "$contains": "POLYGON((7.9 55.4,8.1 55.4,8.1 55.6,7.9 55.6,7.9 55.4))",
    }
}

Since no additional constraints are imposed the query above returns all datasets within the polygon.

Finally, let's combine two search modes in a single query,

{
"https://schemas.geodatahub.dk/organizations/usgs/geophysics/geolog.json": {
    "Category": "Electromagnetic"
},
"geometry": {
    "$contains": "POLYGON ((-70.39215087890625 41.16211393939692, -69.81674194335938 41.16211393939692, -69.81674194335938 41.447873389865194, -70.39215087890625 41.447873389865194, -70.39215087890625 41.16211393939692))",
    }
}

This will return all Geolog datasets of the category Electromagnetic located on the island of Nantucket off the east coast of the US.