Skip to content

Home

Jump to bottom Edit New page
valdeza edited this page Sep 11, 2024 · 88 revisions

iDigBio Search API

https://search.idigbio.org/v2/

Please join our list at idigbio-api-users-l@lists.ufl.edu if you are using our API so we can notify you of changes. You can join via the web at: http://lists.ufl.edu/cgi-bin/wa?A0=IDIGBIO-API-USERS-L

Below is the specification for the iDigBio Search API, also known as the iDigBio API v2. It uses technology and patterns common in other parts of iDigBio to build a wrapper around the full Elasticsearch API, exposing a minimal subset. The code in this repository implements all of the documented functionality, although it may not be bug free or optimal.

There are several things not covered here, such as this API's relation to the v2 Access API. This is one of several APIs available, please review the iDigBio API Overview for more information about additional ways to access iDigBio data.

Overview

The public API supports HTTP GET and POST requests for data read operations only. The iDigBio API is a RESTful web service that delivers data primarily as JSON documents.

GET requests

A query submitted as a GET request must be URL-encoded.

POST requests

A query submitted as a POST request must be supplied as JSON in the content body and specify the "Content-Type: application/json" request header.

Contents

Attribution block

Each request will also return a top level attribution block containing recordset information for recordsets covered by the request, potentially including counts.

View

Basic Access

GET /v2/view/{uuid}
GET /v2/view/{type}/{uuid}

Returns idigbio record format (legacy api), equivalent to the current legacy api.

{type} is one of: records, mediarecords, recordsets, publishers

Search

Basic searching

GET /v2/search/{type}/?{parameters}

{type} is one of: records, mediarecords, recordsets

{parameters} : type-specific query string and parameters

Records

Searching for record objects

GET, POST /v2/search/records/

Deprecated endpoint:

GET, POST /v2/search/
Parameter Description
rq Search Query in iDigBio Query Format, using Record Query Fields
sort field to sort on, pick from Record Query Fields
fields a list of fields to return, specified using the fieldName parameter from Fields with type records
fields_exclude a list of fields to exclude, specified using the fieldName parameter from Fields with type records
limit max results
offset skip results
no_attribution disable the attribution block when set

Returns idigbio record format (legacy api), plus additional top level keys with parsed index terms.

Media

Searching for mediarecord objects

GET, POST /v2/search/media/

Deprecated endpoint:

GET, POST /v2/media/
Parameter Description
mq Search Query in iDigBio Query Format, using Media Query Fields
rq Search Query in iDigBio Query Format, using Record Query Fields
sort field to sort on, pick from Media Query Fields
fields a list of fields to return, specified using the fieldName parameter from Fields with type mediarecords
fields_exclude a list of fields to exclude, specified using the fieldName parameter from Fields with type records
limit max results
offset skip results
no_attribution disable the attribution block when set

Returns idigbio record format (legacy api), plus additional top level keys with parsed index terms.

Recordsets

Searching for recordset objects

GET, POST /v2/search/recordsets/
Parameter Description
rsq Search Query in iDigBio Query Format, using Record Query Fields
sort field to sort on, pick from Record Query Fields
fields a list of fields to return, specified using the fieldName parameter from Fields with type records
fields_exclude a list of fields to exclude, specified using the fieldName parameter from Fields with type records
limit max results
offset skip results

Returns idigbio record format (legacy api), plus additional top level keys with parsed index terms.

Mapping

Create Map

GET, POST /v2/mapping/
Parameter Description
rq Search Query in iDigBio Query Format, using Record Query Fields
style Style is a JSON dictionary that describes how the map is rendered. For most users, the defaults will work without any modification.
type 'geohash' or 'points'

Returns the map definition and attribution information. Also returns the map short code, and URLs to tile endpoints.

For everything below this, the parameter {s} is the map short code, which is returned in the JSON response of the map creation. Think of this short code like a url shortener for your whole map query.

Retrieve Map Definition

GET /v2/mapping/{s}

Returns the map definition and attribution information. Also returns the map short code, and URLs to tile endpoints.

{s} is a map short code

Tiled GeoJSON

GET, POST /v2/mapping/{s}/{z}/{x}/{y.json}

Returns a GeoJSON representation of the map point or geohash data.

Tiled UTF-8 grid

GET, POST /v2/mapping/{s}/{z}/{x}/{y.grid.json}

Returns a utf8grid representation of the map point or geohash data.

Tiled PNG

GET, POST /v2/mapping/{s}/{z}/{x}/{y.png}

Returns a PNG representation of the map point or geohash data.

Map Points

GET, POST /v2/mapping/{s}/points
Parameter Description
lat Latitude of the map click
lon Longitude of the map click
zoom current zoom level of the map
sort Field to sort on, pick from Record Query Fields
limit max results
offset skip results

Returns points "near" a click location on a map. Primarily useful for retrieving data for a map popup on click event. Returns a data format identical to basic searching.

Summary

Top-N Records

GET, POST /v2/summary/top/records/

Deprecated endpoint:

GET, POST /v2/summary/top/basic/
Parameter Description
rq Search Query in iDigBio Query Format, using Record Query Fields
top_fields a list of fields to return, specified using the fieldName parameter from Fields with type records
count The number of top value to return

Returns a custom JSON format containing the top-N (where n is specified with count) values for a given field. Scientificname is the default field. When multiple fields are supplied, the values will be nested inside each-other. This allows you to build field heirarchies. For example:

/v2/summary/top/records/?top_fields=["kingdom","phylum"]&count=10

Will return the top 10 kingdoms for all records, and the top 10 phylums for each kingdom.

Top-N Mediarecords

GET, POST /v2/summary/top/media/
Parameter Description
mq Search Query in iDigBio Query Format, using Media Query Fields
rq Search Query in iDigBio Query Format, using Record Query Fields
top_fields a list of fields to return, specified using the fieldName parameter from Fields with type mediarecords
count The number of top value to return

As in Top-N-Records, but supporting media queries, and fields from the mediarecord type. Flags is the default summary field.

Record Count

GET, POST /v2/summary/count/records/

Deprecated endpoint:

GET, POST /v2/summary/count/basic/
Parameter Description
rq Search Query in iDigBio Query Format, using Record Query Fields

Returns the number of records that match a search.

Media Count

GET, POST /v2/summary/count/media/
Parameter Description
mq Search Query in iDigBio Query Format, using Media Query Fields
rq Search Query in iDigBio Query Format, using Record Query Fields

Returns the number of media records that match a search.

Recordset Count

GET, POST /v2/summary/count/recordsets/
Parameter Description
rsq Search Query in iDigBio Query Format, using Recordset Query Fields

Returns the number of recordsets that match a search.

Record Modified

GET, POST /v2/summary/modified/records/
Parameter Description
rq Search Query in iDigBio Query Format, using Record Query Fields

Returns the last time a record was modified in idigbio that matches the search.

Media Modified

GET, POST /v2/summary/modified/media/
Parameter Description
mq Search Query in iDigBio Query Format, using Media Query Fields
rq Search Query in iDigBio Query Format, using Record Query Fields

Returns the last time a mediarecord was modified in idigbio that matches the search.

Date Histogram

GET, POST /v2/summary/datehist
Parameter Description
rq Search Query in iDigBio Query Format, using Record Query Fields
top_fields a list of fields to return as sub fields of the histogram, specified using the fieldName parameter from Fields with type records
count The number of top value to return
date_field (or dateField) the index date field to compute the histogram on (datecollected by default)
min_date (or minDate) the minimum date to display, supports raw dates, and date math (see: Date Math)
max_date (or maxDate) the maximum date to display, same formats as minDate
date_interval (or dateInterval) The interval of the histogram, supports year, month, week, day (year by default)

Display data bucketed by date fields, useful for building charts or histograms. Supports the same parameters as the Top-N Records endpoint for nesting data inside the histogram buckets.

Stats

GET, POST /v2/summary/stats/{t}
Parameter Description
t Stat type, one of: api, digest, search
recordset Limit the display to a single recordset (by uuid).
min_date (or minDate) the minimum date to display, supports raw dates, and date math (see: Date Math)
max_date (or maxDate) the maximum date to display, same formats as minDate
date_interval (or dateInterval) The interval of the histogram, supports year, month, week, day (year by default)

Display stats data bucketed by date fields, useful for building charts or histograms. Stats returned depend on type:

  • API: Returns the Count of Records and Mediarecords per Recordset from our API stats for the date range
  • Digest: Returns the Count of Records and Mediarecords per Recordset from our Digest stats for the date range
  • Search: Returns the usage stats for our system for the date range
    • Search: Count of records per recordset matching search queries
    • Seen: Count of records per recordset displayed to users (or returned with data from the API)
    • Download: Count of records per recordset download via the download system

Metadata

Fields

GET, POST /v2/meta/fields/{type}

Returns a dictionary of fields and subfields, their types, and fully qualified field names.

{type} is one of: records, mediarecords, recordsets, publishers

Add a custom footer
Add a custom sidebar
Clone this wiki locally