Skip to content

Populate, Search, and Query

So your agency knows only some of the information about a record and wants to find the rest of it through the VectorSurv API. What would this process look like?

Let's look at an example: The manager of a local control agency, Hector, wants to check the collection number and abundance details of a certain collection. Hector knows that he identified the species in May 2023, and that when the collection was entered into VectorSurv the comments included the phrase "first albo detection". Hector can use the information he has to get the details he wants through the API.

Basic Request

A basic idea would be to GET all of the available collections for Hector's agency and have him decipher the one he wants.

Basic Request example

getCollections.js
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
async function getCollections() {
  const config = {
    headers: {
      Authorization: "Bearer Hector_auth_token",
      "Content-Type": "application/json",
    },
    params: {},
  };

  const url = "https://api.vectorsurv.org/v1/arthropod/collection";

  try {
    const response = await axios.get(url, config);
    console.log("Response:", response.data);
  } catch (error) {
    console.error("Error:", error.response.data);
  }
}
getCollections.r
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
library(httr)
library(jsonlite)

getCollections <- function(token) {
  headers = c(
    Authorization = paste("Bearer", token),
    "Content-Type" = "application/json"
  )

  url <- "https://api.vectorsurv.org/v1/arthropod/collection"

  tryCatch({
    # Make the API request
    response <- GET(url, add_headers(headers))

    # Check the response status code and category
    status_code <- http_status(response)$status_code
    status_category <- http_status(response)$category

    # Check the status code of the response
    if (status_category == "Success") {
      # Response status is successful (e.g., status code 200)
      content <- httr::content(response, "text")
      # Use this data frame as needed
      content_df = fromJSON(content)
      print(content_df)
    } else {
      # Request failed, display an error message
      response_content <- httr::content(response, 'text')
      message("Error response content:", response_content)
    }
  }, error = function(e) {
    # Any other exceptions that might occur during the API request
    message("An error occurred during the API request. Error message:", e$message)
  })
}

getCollections("Hector_auth_token")

curl -X GET 'https://api.vectorsurv.org/v1/arthropod/collection' \
-H 'Authorization: Bearer Hector_auth_token' \
-H 'Content-Type: application/json'

While this would find Hector some of the information he's looking for, improvements can be made.

Populate

The populate parameter triggers an expanded response from the API. Only certain fields are eligible for populate. In Hector's case, he should populate the arthropods value to get the abundance associated with his collections.

Populate Request example

getCollectionsWithPopulate.js
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
async function getCollections() {
  const config = {
    headers: {
      Authorization: "Bearer Hector_auth_token",
      "Content-Type": "application/json",
    },
    params: {
      "populate": ["arthropods"],
    },
  };

  const url = "https://api.vectorsurv.org/v1/arthropod/collection";

  try {
    const response = await axios.get(url, config);
    console.log("Response:", response.data);
  } catch (error) {
    console.error("Error:", error.response.data);
  }
}
getCollections.r
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
library(httr)
library(jsonlite)

getCollections <- function(token) {
  headers = c(
    Authorization = paste("Bearer", token),
    "Content-Type" = "application/json"
  )

  url <- "https://api.vectorsurv.org/v1/arthropod/collection"

  query = list(
    `populate[]` = "arthropods"
  )

  tryCatch({
    # Make the API request
    response <- GET(url, add_headers(headers), query = query)

    # Check the response status code and category
    status_code <- http_status(response)$status_code
    status_category <- http_status(response)$category

    # Check the status code of the response
    if (status_category == "Success") {
      # Response status is successful (e.g., status code 200)
      content <- httr::content(response, "text")
      # Use this data frame as needed
      content_df = fromJSON(content)
      print(content)
    } else {
      # Request failed, display an error message
      response_content <- httr::content(response, 'text')
      message("Error response content:", response_content)
    }
  }, error = function(e) {
    # Any other exceptions that might occur during the API request
    message("An error occurred during the API request. Error message:", e$message)
  })
}

getCollections("Hector_auth_token")

curl -X GET 'https://api.vectorsurv.org/v1/arthropod/collection?populate[]=arthropods' \
-H 'Authorization: Bearer Hector_auth_token' \
-H 'Content-Type: application/json'

Search and SearchFields

The search and searchFields params combine to cause the API to filter responses based on the contents of text fields. In Hector's case, he should search for "first albo detection" in the comments searchField.

Search and SearchFields Request example

getCollectionsWithPopulateAndSearch.js
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
async function getCollections() {
  const config = {
    headers: {
      Authorization: "Bearer Hector_auth_token",
      "Content-Type": "application/json",
    },
    params: {
      populate: ["arthropods"],
      search: "first albo detection",
      searchFields: ["comments"],
    },
  };

  const url = "https://api.vectorsurv.org/v1/arthropod/collection";

  try {
    const response = await axios.get(url, config);
    console.log("Response:", response.data);
  } catch (error) {
    console.error("Error:", error.response.data);
  }
}
getCollectionsWithPopulateAndSearch.r
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
library(httr)
library(jsonlite)

getCollections <- function(token) {
  headers = c(
    Authorization = paste("Bearer", token),
    "Content-Type" = "application/json"
  )

  url <- "https://api.vectorsurv.org/v1/arthropod/collection"

  query = list(
    `populate[]` = list("arthropods"),
    search = "first albo detection",
    `searchFields[]` = list("comments")
  )

  tryCatch({
    # Make the API request
    response <- GET(url, add_headers(headers), query = query)

    # Check the response status code and category
    status_code <- http_status(response)$status_code
    status_category <- http_status(response)$category

    # Check the status code of the response
    if (status_category == "Success") {
      # Response status is successful (e.g., status code 200)
      content <- httr::content(response, "text")
      # Use this data frame as needed
      content_df = fromJSON(content)
      print(content)
    } else {
      # Request failed, display an error message
      response_content <- httr::content(response, 'text')
      message("Error response content:", response_content)
    }
  }, error = function(e) {
    # Any other exceptions that might occur during the API request
    message("An error occurred during the API request. Error message:", e$message)
  })
}

getCollections("Hector_auth_token")

curl -X GET "https://api.vectorsurv.org/v1/arthropod/collection?populate[]=arthropods&search=first%20albo%20detection&searchFields[]=comments" \
-H "Authorization: Bearer Hector_auth_token" \
-H "Content-Type: application/json"

Query

The query param cause the API to apply certain database-style filters. In Hector's case, he should query for a collection_date between the last day of April and the first day of June.

Query param Request example

getCollectionsWithPopulateAndSearchAndQuery.js
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
async function getCollections() {
  const url = "https://api.vectorsurv.org/v1/arthropod/collection";

  const config = {
    headers: {
      Authorization: "Bearer Hector_auth_token",
      "Content-Type": "application/json",
    },
    params: {
      populate: ["arthropods"],
      search: "first albo detection",
      searchFields: ["comments"],
      "query[collection_date][$between][0]": "2023-04-30",
      "query[collection_date][$between][1]": "2023-06-01",
    },
  };

  const url = "https://api.vectorsurv.org/v1/arthropod/collection";

  try {
    const response = await axios.get(url, config);
    console.log("Response:", response.data);
  } catch (error) {
    console.error("Error:", error.response.data);
  }
}
getCollectionsWithPopulateAndSearchAndQuery.r
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
library(httr)
library(jsonlite)

getCollections <- function(token) {
  headers = c(
    Authorization = paste("Bearer", token),
    "Content-Type" = "application/json"
  )

  url <- "https://api.vectorsurv.org/v1/arthropod/collection"

  query <- list(
    `populate[]` = list("arthropods"),
    search = "first albo detection",
    `searchFields[]` = list("comments"),
    `query[collection_date][$between][0]` = "2023-04-30",
    `query[collection_date][$between][1]` = "2023-06-01"
  )

  tryCatch({
    # Make the API request
    response <- GET(url, add_headers(headers), query = query)

    # Check the response status code and category
    status_code <- http_status(response)$status_code
    status_category <- http_status(response)$category

    # Check the status code of the response
    if (status_category == "Success") {
      # Response status is successful (e.g., status code 200)
      content <- httr::content(response, "text")
      # Use this data frame as needed
      content_df = fromJSON(content)
      print(content)
    } else {
      # Request failed, display an error message
      response_content <- httr::content(response, 'text')
      message("Error response content:", response_content)
    }
  }, error = function(e) {
    # Any other exceptions that might occur during the API request
    message("An error occurred during the API request. Error message:", e$message)
  })
}

getCollections("Hector_auth_token")

    curl -X GET 'https://api.vectorsurv.org/v1/arthropod/collection?populate[]=arthropods&search=first%20albo%20detection&searchFields[]=comments&query[collection_date][$between][0]=2023-04-30&query[collection_date][$between][1]=2023-06-01' \
    -H 'Authorization: Bearer Hector_auth_token' \
    -H 'Content-Type: application/json'