API documentation

Getting started

URLs are structured by entering the API directory and appending the subgenus and species.json to the base URL:

https://themelissodesproject.wildref.org/api/{subgenus}/{species}.json

Lists of all URLs, along with subgeneric and species classification can be foud here:

https://themelissodesproject.wildref.org/api/species-index.json

Data structure

Each species follows the same Json file structure with five overarching classes: taxanomic data, flight period, distribution summary, occurences, and metadata. Examples of these structures are provided below.

Taxanomic data:

{
  "binomial_name": "Melissodes agilis",
  "common_name": "Agile Long-horned Bee",
  "taxonomy": {
    "family": "Apidae",
    "subfamily": "Apinae",
    "tribe": "Eucerini",
    "genus": "Melissodes",
    "subgenus": "Eumelissodes",
    "species": "agilis"
}
}

Flight period:

{
 "flight_period": {
  "June": {
     "count": 1161,
    "percentage": 7.37
  },
  "July": {
    "count": 3513,
    "percentage": 22.32
  },
  "August": {
  "count": 9654,
  "percentage": 61.34
  },
  "September": {
    "count": 1480,
    "percentage": 9.41
  },
}
}

Overall, this section is an automatic summary of the data in the "observations" class. Two subsections are given per month (months without any observations are automatically excluded in each species Json), "count" and "percentage". In this example, this species was only active during four months out of the year, June, July, August, and September. The percentages per month are given as a means of normalization, for example, when trying to identify months of peak activity, M. agilis may have ~9,000 records their peak activity month, but less common species (eg. M. bicoloratus) may not even have a total of 9,000 records. So, instead of calculating peak activity using a numerical value, percentages can be better utilized for such tasks.

Distribution summary:

"distribution": {
    "Delaware": {
      "state_total": 1,
      "counties": {
        "Nan": {
          "count": 1
        }
      }
    },
    "California": {
      "state_total": 2441,
      "counties": {
        "Stanislaus": {
          "count": 203
        },
        "Riverside": {
          "count": 34
        },
        "Sanbernardino": {
          "count": 7
        },
        "Santaclara": {
          "count": 1
        },
        "Losangeles": {
          "count": 1
    },
  }
}
}

Similarly to that of the flight period, this section is a summary of what's found in the occurrences. Each state is given three fields, state total (state_total), counties (counties), and number of specimens per county (count). The distribution summary is less for in-depth record accounts, and more for listing state records.

Occurences:

"occurrences": [
{
  "gbifID": "3801851843",
  "gbif_link": "https://www.gbif.org/occurrence/3801851843",
  "location": {
    "state": "Illinois",
    "county": "Fayette",
    "locality": null,
    "coordinates": {
      "lat": "38.8747",
      "lon": "-88.7756"
    }
  },
  "temporal": {
    "date": "1966-07-20",
    "month": "7.0",
    "year": "1966.0"
  },
  "collector": {
    "recordedBy": "W.E. LaBerge, W.J. Knee",
    "identifiedBy": null
  },
  "ecology": {
    "notes": "ILL., 3 mi N of Farina, Fayette Co.; 20-VII-66; Knee, LaBerge; On Silphium laciniatum  Melissodes (Eumelissodes) agilis Cresson; det. W.E. LaBerge",
    "extracted_floral_hosts": [
      {
        "original_query": "Silphium laciniatum",
        "accepted_genus": "Silphium",
        "accepted_species": "laciniatum",
        "canonical_name": "Silphium laciniatum"
      }
    ]
  },
  "citation": {
    "text": "McElrath T (2023). Illinois Natural History Survey Insect Collection. Illinois Natural History Survey. Occurrence dataset https://doi.org/10.15468/eol0pe accessed via GBIF.org on 2025-12-19.",
    "license": "CC BY 4.0"
  }
}
]

The occurrence section is where the majority of the data (and the json structure) lie; the small example above is a single Melissodes agilis observation. Each observational section can be split into five subsections, location and occurrence id (gbifID, gbif_link, and location), date (temporal), collection attribution (collector), bionomics (ecology), and the observation attribution (citation). Although the first three and last sections are somewhat self explanatory, "ecology" is processed slightly differently. As can be observed from the presence of GBIF identifiers, data is aggregated from GBIF, then filtered and parsed using AI floral recognition to organize previously "hidden records". This is done by parsing through “fieldNotes”, “verbatimLabel”, “occurrenceRemarks”, and “associatedTaxa” columns from occurrence.txt records in GBIF Darwincore Archives. If a flower species is found in any one of these columns, the entire present string is added to the “notes” field in the ecology subsection (in the example above, this would be the case of a “verbatimLabel” having a flower present and being added to a general “notes” feild). After which the string of characters in which the AI interprets as a flower is checked against the GBIF API backend to ensure the predicted taxa exists (these are the characters in the "original_query" field). Once greenlighted, the genus ("accepted_genus") and species ("accepted_species") are extracted and then reassembled into the final binomial name ("canonical_name"). This safeguard is put in place so if a typo of a certain flower taxa occurs, the canonical_name field is combining character strings strictly from GBIF API output and the error becomes isolated. Note, this is still AI interpretation and will therefore likely extract incorrect strings of predicted taxa (e.g. a label may read “3 mi W; Sterling, Ida.; Bingham Co.; IX-17-1954 Melissodes; rivalis Cresson; det. W. E. LaBerge A.R.Gittins; Collector,” and the AI may detect “Ida” as a flower, given it’s a valid genus, even though this instead is an abbreviation for Idaho). In cases such as these, it’s important to check the context of the label, hence the reason for its presence.

Metadata:

"metadata": {
  "project_name": "The Melissodes Project",
  "total_records": 17066,
  "geospatial_fixes": 1226,
  "contributing_datasets": [
    "Gross J, Oboyski P (2025). Essig Museum of Entomology. Version 121.421. Berkeley Natural History Museums. Occurrence dataset https://doi.org/10.15468/0saucj accessed via GBIF.org on 2025-12-19. (CC BY 4.0)",
    "Gibbs J (2025). J. B. Wallis / R. E. Roughley Museum of Entomology. Version 1.2. University of Manitoba. Occurrence dataset https://doi.org/10.5886/hgagiy accessed via GBIF.org on 2025-12-19. (CC BY 4.0)",
    "Bentley A, Osborn R (2025). Snow Entomological Museum Collection. University of Kansas Biodiversity Institute. Occurrence dataset https://doi.org/10.15468/fhntpy accessed via GBIF.org on 2025-12-19. (CC BY 4.0)",
    "McElrath T (2023). Illinois Natural History Survey Insect Collection. Illinois Natural History Survey. Occurrence dataset https://doi.org/10.15468/eol0pe accessed via GBIF.org on 2025-12-19. (CC BY 4.0)",
    "Ikerd H (2019). Bee Biology and Systematics Laboratory. USDA-ARS Pollinating Insect-Biology, Management, Systematics Research. Occurrence dataset https://doi.org/10.15468/anyror accessed via GBIF.org on 2025-12-19. (CC BY 4.0)",
    "Colorado State University, C.P. Gillette Museum of Arthropod Diversity (2025). C.P. Gillette Museum of Arthropod Diversity. Occurrence dataset https://doi.org/10.15468/k0aett accessed via GBIF.org on 2025-12-19. (CC0 1.0)",
    "University of Minnesota Insect Collection (2025). University of Minnesota Insect Collection. Occurrence dataset https://doi.org/10.15468/ahwyqb accessed via GBIF.org on 2025-12-19. (CC0 1.0)",
    "Oram R (2025). Royal Saskatchewan Museum - Entomology. Version 2.1. Royal Saskatchewan Museum. Occurrence dataset https://doi.org/10.5886/osnmhn accessed via GBIF.org on 2025-12-19. (CC BY 4.0)",
    "Scott V (2025). UCM Entomology Collection. Version 6.6. University of Colorado Museum of Natural History. Occurrence dataset https://doi.org/10.15468/jsgtns accessed via GBIF.org on 2025-12-19. (CC BY-NC 4.0)",
    "MT James Entomological Collection, Washington State University (2025). Washington State University Collection. Occurrence dataset https://doi.org/10.15468/c8yk6t accessed via GBIF.org on 2025-12-19. (CC BY-NC 4.0)"
  ]
}

Metadata is the final section of the Json file structure, consisting mostly of dataset-wide citations and observational counts. Each citation has its corresponding license dynamically appended for the specific database used. Along with this, the total number of geospatial fixes are given, which are observations that have coordinates but no state and/or county defined that have been updated with these corrected values.

Attribution

The Melissodes Project API aggregates data from several datasets. When using this API, please cite each dataset as follows:

1. Using the “text” object under “citation” for proper full citations of each record (if using the full, unaltered dataset, this can be done from the "contributing_datasets" object under “metadata” for a full list of all datasets).

2. Abide by the "license" object under “citation” of each record.

The Melissodes Project takes no ownership over any of the data, all credit should go to the individual datasets.

The Melissodes Project API Documentation