Skip to content

Site

Sites are essentially bookmarks for trap locations. New sites should be created whenever surveillance may occur more than once in the same location. Learn more about sites

Notes

Revisions

Each site is considered one temporal version of a site code. The same site code may have multiple revisions that span different time periods. We do this because an agency may want to consider one site area as a single site code, but pinpoint the exact location or site qualities as they change over time.

Shape

The shape object defines the site's spatial identity.

The '000000' site

When a new surveillance effort record is created in the VectorSurv system, a corresponding geospatial record is created if that record has a geospatial component. To add context to surveillance efforts, a site can be associated with many types of records when those records are created, and the corresponding geospatial record created for the new surveillance effort will be derived from the site by default. This is an excellent solution for locations with repeated surveillance. The site with code 000000, also known as the 'Zero Site', should be associated with non-recurring surveillance efforts.

Creating a Site Revision

URL: /v1/site

Request Type: POST

Request:

Parameters

General
Name Type Description
active_date string Date on which site was first used for surveillance.
address_1 string Address or nearest intersection to coordinates.
address_2 string Additional address or intersection details.
agency number Internal ID referencing the agency to which the site belongs.
city string Address city.
code string Required. 6 digit numeric code. Must be unique in the agency.
comments string Any comments associated with the site. Comments are not public.
coordinate_precision number Required. Internal ID corresponding to the level of preciseness associated with this site's coordinates.
elevation number Elevation at site.
deactive_date string Date after which site was never again used for surveillance.
name string Required. Site name.
postal_code string 5 digit zip code.
region number Internal ID corresponding to the region (state, county, etc.) in which the site is located. Defaults to agency's region.
revision_comments string Comments about this iteration of the site. Applicable in cases where the same code is used in distinct time periods.
shape object Required. Shape object.
user number Internal ID corresponding to the user creating the site.
site_population string The human population density in the vicinity of the site.
site_land_usage array Array of internal IDs corresponding to land usage surrounding the site. Common land usage types ("Agricultural", "Commercial", etc.) will have existing land usage types in the database.
site_land_usage_custom array Array of strings, where each is a description of a type of land usage not already represented in the database ("Flood Plain", for instance).
Shape Object
Name Type Description
type string GIS geometry type. For sites, the correct value is "Point".
coordinates array Geographical coordinates, such that [longitude, latitude]. If the longitude is in the western hemisphere, the value must be prefixed by the minus '-' sign. If the latitude is in the southern hemisphere, the value must be prefixed by the minus '-' sign. Longitude must be between -90 and 90. Latitude must be between -180 and 180.

Sample request body

sample_site_request_body.json
{
  "active_date": "1970-01-01T00:00:00.000Z",
  "address_1": "123 Main Street",
  "address_2": "",
  "agency": 123,
  "city": "Springfield",
  "code": "123456",
  "comments": "Empty lot behind the emporium",
  "coordinate_precision": 2,
  "elevation": 123,
  "deactive_date": "2000-01-01T00:00:00.000Z",
  "name": "Emporium Oak Tree",
  "postal_code": "12345",
  "region": 12,
  "shape": {
    "type": "Point",
    "coordinates": [-123, 34]
  },
  "user": 123,
  "site_population": "Suburban",
  "site_land_usage": [1],
  "site_land_usage_custom": ["Down by the old mill stream"]
}

Response:

Data

Name Type Description
active_date string Date on which site was first used for surveillance.
code string Six digit numeric code assigned to site.
name string Site name.
coordinate_precision number Internal ID corresponding to the level of preciseness associated with this site's coordinates.
shape string Site Shape Object.
region number Internal ID corresponding to the region (state, county, etc.) in which the site is located.
agency number Internal ID referencing the agency to which the site belongs.
deactive_date string Date after which site was never again used for surveillance.
elevation string Elevation at coordinates.
user number Internal ID corresponding to the user that created the site.
add_date string Date created.
updated string Date last updated.
id number Internal ID corresponding to the site.
address_1 string Address or nearest intersection to coordinate.
address_2 string Additional address or intersection details.
city string Address city.
postal_code string 5 digit zip code.
comments string Any comments associated with the site.
delete_date string Date after which the site no longer exists.
revision_comments string Comments about this iteration of the site. Applicable in cases where the same code is used in distinct time periods.

Sample response body

sample_site_create_response.json
{
  "active_date": "1970-01-01T00:00:00.000Z",
  "address_1": "123 Main Street",
  "address_2": "",
  "agency": 123,
  "city": "Springfield",
  "code": "123456",
  "comments": "Empty lot behind the emporium",
  "coordinate_precision": 2,
  "elevation": 123,
  "deactive_date": "2000-01-01T00:00:00.000Z",
  "name": "Emporium Oak Tree",
  "postal_code": "12345",
  "region": 12,
  "revision_comments": "",
  "shape": {
    "type": "Point",
    "coordinates": [-123, 34]
  },
  "user": 123,
  "id": 456,
  "add_date": "2023-01-01T04:16:46.036Z",
  "site_population": "Suburban",
  "site_land_usage": [1],
  "site_land_usage_custom": ["Down by the old mill stream"],
  "updated": "2023-01-01T04:16:46.037Z"
}

Retrieving a Site Revision

URL: /v1/site/{id}

Request Type: GET

Request

Parameters

General
Name Type Description
populate[] array Interior fields to be expanded. Possible values: user, agency, coordinate_precision, original_location.
sort query Order for returned records. Default will be provided.
fields[] array Fields to include in response.
page number Page number.
page size number Number of results per page.
search string Pattern to search for.
searchFields[] array Array of fields to be pattern searched. String fields only.
query array Supplemental postgres queries.

Sample Request Body

sample_site_request.json
{
  "id": 456
}

Response

Sample Response Body

sample_response.json
{
  "active_date": "1980-01-01T00:00:00.000Z",
  "address_1": "123 Main Street",
  "address_2": "",
  "agency": 123,
  "city": "Springfield",
  "code": "123456",
  "comments": "Empty lot behind the emporium",
  "coordinate_precision": 2,
  "elevation": 123,
  "deactive_date": "2000-01-01T00:00:00.000Z",
  "name": "Emporium Birch Tree",
  "postal_code": "12345",
  "region": 12,
  "revision_comments": "",
  "shape": {
    "crs": {
      "type": "name",
      "properties": {
        "name": "EPSG:4326"
      }
    },
    "type": "Point",
    "coordinates": [-123, 34]
  },
  "user": 123,
  "site_population": "Suburban",
  "site_land_usage": [1],
  "site_land_usage_custom": ["Down by the old mill stream"]
}

Updating a Site Revision's Location

URL: /v1/site/{id}/move-within-radius

Request Type: PUT

This endpoint allows you to alter a site's location within a certain radius of the original location.

Request

all fields optional except for id and shape

Name Type Description
address_1 string Address or nearest intersection to coordinates.
address_2 string Additional address or intersection details.
agency number Internal ID referencing the agency to which the site belongs.
city string Address city.
code string 6 digit numeric code. Must be unique in the agency.
comments string Any comments associated with the site. Comments are not public.
coordinate_precision number Internal ID corresponding to the level of preciseness associated with this site's coordinates.
elevation number Elevation at site.
name string Site name.
postal_code string 5 digit zip code.
region number Internal ID corresponding to the region (state, county, etc.) in which the site is located.
revision_comments string Comments about this iteration of the site. Applicable in cases where the same code is used in distinct time periods.
shape object Shape object.
user number Internal ID corresponding to the user creating the site.
site_population string The human population density in the vicinity of the site.
site_land_usage array Array of internal IDs corresponding to land usage surrounding the site. Common land usage types ("Agricultural", "Commercial", etc.) will have existing land usage types in the database.
site_land_usage_custom array Array of strings, where each is a description of a type of land usage not already represented in the database ("Flood Plain", for instance).

Sample Request Body

{
  "id": 010132,
  "shape": {
    "type": "Point",
    "coordinates": [-119.99999, 37.9998]
  }
}

Updating a Site Revision's Active and Deactive Dates

URL: /v1/site/{id}/update-dates-safely

Request Type: PUT

If this change would cause any linked collections, pools, or sentinel results to no longer match their linked site's time range, then you will receive a validation error.

Request

Name Type Description
active_date string Date on which site was first used for surveillance.
agency number Internal ID referencing the agency to which the site belongs.
code string 6 digit numeric code. Must be unique in the agency.
comments string Any comments associated with the site. Comments are not public.
deactive_date string Date after which site was never again used for surveillance.
name string Site name.
revision_comments string Comments about this iteration of the site. Applicable in cases where the same code is used in distinct time periods.
user number Internal ID corresponding to the user creating the site.
site_population string The human population density in the vicinity of the site.
site_land_usage array Array of internal IDs corresponding to land usage surrounding the site. Common land usage types ("Agricultural", "Commercial", etc.) will have existing land usage types in the database.
site_land_usage_custom array Array of strings, where each is a description of a type of land usage not already represented in the database ("Flood Plain", for instance).

Sample Request Body

{
  "active_date": "1980-01-01T00:00:00.000Z",
  "id": 2130
}

Updating Adjacent Site Revisions

URL: /v1/site/update-adjacent-site-revisions

Request Type: PUT

If you have two site revisions that share a temporal boundary, and you wish to shift that temporal boundary, this is the best way to do so. Any linked records that are associated with one site revision that would fall into the timeline of a different site revision following this shift will be updated to be linked to that different site revision.

Request

Name Type Description
sites array

Sample Request Body

{
  "sites": [
    { 
      "id": 1,
      "active_date": "2000-01-01",
      "deactive_date": "2010-01-01"
    }, 
    {
      "id": 2,
      "active_date": "2010-01-01",
      "deactive_date": null
    }
  ]
}

Note how the site revision with id 1 has a deactive_date that equals the active_date of site revision with id 2.

This endpoint is how you can safely change that shared boundary on both site revisions.

In this example, "2010-01-01" is the new boundary value that is to update the previously shared boundary.

You cannot also change site revision 1's active_date, or site revision 2's deactive_date, in this same endpoint. To make those changes, use the change-dates-safely endpoint.