Web Services
Table of contents
Import
Introduction
The VectorSurv Gateway (here-in called the Gateway) import web service provides local agencies the ability to import new records. This service is primarily intended for consumption by local in-house applications.
Requirements
The Gateway import web service is secured and require authentication. Authentication is done by providing an Agency Token generated by the Gateway. To generate an Agency Token, your Gateway account must be an Agency Manager. If not, you will need to ask someone from your agency with Agency Manager access to generate you a token.
Agency tokens can be generated through the Agency Tokens item found in the My Agency section of the Settings menu. Each token is associated with the user who generated the token, the agency of the user and the privileges of the user. Therefore, any data imported is done as the user and agency who generated the token.
Conventions
The following conventions are used when describing the structure and format of the JSON-encoded import data.
If a key-value pair is optional, the pair will be enclosed with the less-than (<) and greater-than (>) characters.
<"name":"SITE_NAME",>
...
...
"coordinates": {
"latitude": {
"degrees":"DEGREES",
<"minutes":"MINUTES",
<"seconds":"SECONDS">>
},
"longitude": {
"degrees":"DEGREES",
<"minutes":"MINUTES",
<"seconds":"SECONDS">>
}
},
<"population":"(urban|suburban|rural|auto)",>
...
...
<"elevation": ({
"units":"(m|ft)",
"value":"(ELEVATION|auto)"
} |
"(ELEVATION|auto)",>
The specifications below may not list all the possible values for a key. This is particularly true for the format key of date values where it is best to check on the Gateway what date formats are available.
Upper-case strings are used to denote values provided by the request.
Basic Request Structure
The import web-service is a POST request with some parameters provided in the URL query and the import data JSON-encoded in a POST variable.
https://gateway.vectorsurv.org/ws.php?module=core&ppf=import.ws&output=json&token=TOKEN The POST request contains the variable insert whose value is a JSON-encoded string of the data to be imported into the Gateway.
Permitted user URL parameters are:
output Determines the format used to encapsulate the response from the web service. Permitted values are: json (default), xml, html, text. token Agency token generated by the Gateway using the Agency Tokens tool The JSON object to be passed to the web service through the insert POST variable has the following structure.
The JSON object contains one key recordset.
recordset
must an array of one or more objects Each element of the recordset array is an object comprised of three keys.
type
Indicates the type of recordset. This is used to direct how the recordset is processed. Permitted values are: site, arthro, sentinel.
subtype
Required when type = arthro or sentinel. For type = arthro, values can be: collection, pool. For type = sentinel, values can be: band, bleed.
record
must be an array of one or more objects Since the recordset and record variables are arrays of objects, it is possible to import many recordsets of many records in one call to the import web service.
In PHP, the insert POST variable would look like the following.
Response Structure
It is strongly recommended that the URL parameter output be set to json or not be provided as JSON provides structure not found in the other output formats. This section assumes that the response is a JSON object.
The response object has the following structure.
Though there are three keys in the structure, the actual response to a web service request may contain one, two or all three keys. If there are no errors in the processing of the web service request, the response will not have the Error key. The same is true for the other keys.Example
{
"Error": [
"(Recordset 1, Record 1) The value provided for \"code\" key does not match the required format: ######.",
"(Recordset 5) Attribute \"subtype\" missing from "recordset" key.",
"(Recordset 6) Missing \"record\" key from recordset.",
"(Recordset 7) Value provided for attribute \"subtype\" from \"recordset\" key is unknown."
],
"Success": [
"(Recordset 2) The import of the recordset completed successfully.",
"(Recordset 3) The import of the recordset completed successfully.",
"(Recordset 4) The import of the recordset completed successfully."
]
}
Specific Request Structure
Surveillance Site
The object structure for an element of the record array looks like the following.
{
"type":"site",
"record":[{
"code":"SITE_CODE",
<"name":"SITE_NAME",>
"coordinates": {
"latitude": {
"degrees":"DEGREES",
<"minutes":"MINUTES",
<"seconds":"SECONDS">>
},
"longitude": {
"degrees":"DEGREES",
<"minutes":"MINUTES",
<"seconds":"SECONDS">>
}
},
<"coordinate_precision":"(Exact|Unknown|Approximate|City|County)",>
<"elevation": ({
"units":"(m|ft)",
"value":"(ELEVATION|auto)"
} |
"(ELEVATION|auto)"
),>
<"address": {
"primary":"PRIMARY",
<"secondary":"SECONDARY",>
"city":"CITY",
"postal":"POSTAL",
"county":"COUNTY",
"state":"STATE",
"country":"COUNTRY"
},>
<"landusage": [
"LAND_USAGE",
...
"LAND_USAGE"
],>
<"population":"(urban|suburban|rural|auto)",>
<"comments":"COMMENTS">
},
{}]
}
{
"recordset":[{
"type":"site",
"record":[{
"code":"543211",
"name":"Putah Creek State Wildlife Area",
"coordinates": {
"latitude": "38.503472",
"longitude": "-122.086464"
},
"coordinate_precision":"Exact",
"elevation": {
"units":"ft",
"value":2000
},
"address": {
"primary":"6850 State Highway 128",
"city":"Napa",
"postal":"94558",
"county":"Napa",
"state":"CA",
"country":"USA"
},
"landusage": [
"Wildlife Refuge",
"Forest"
],
"population":"rural",
"comments":"Somewhere in the area"
}, {
"code":"543212",
"name":"Putah Creek State Wildlife Area",
"coordinates": {
"latitude": {
"degrees": "38.503472"
},
"longitude": {
"degrees": "-122.086464"
}
},
"coordinate_precision":"City",
"elevation": {
"units":"m",
"value":30
},
"address": {
"primary":"6850 State Highway 128",
"secondary": "Somewhere along 128",
"postal":"94558",
"county":"Napa",
"state":"CA"
},
"landusage": [
"Wildlife Refuge",
"Undeveloped"
],
"population":"rural",
"comments":"Somewhere in the area"
}, {
"code":"543213",
"name":"Putah Creek State Wildlife Area",
"coordinates": {
"latitude": {
"degrees": 38,
"minutes": 30.20832
},
"longitude": {
"degrees": "-122.086464"
}
},
"elevation": {
"value":30
},
"address": {
"primary":"6850 State Highway 128",
"secondary": "Somewhere along 128",
"postal":"94558",
"county":"Napa",
"state":"CA"
},
"landusage": [
"Wildlife Refuge",
"Undeveloped"
],
"population":"rural",
"comments":"Somewhere in the area"
}, {
"code":"543214",
"name":"Putah Creek State Wildlife Area",
"coordinates": {
"latitude": {
"degrees": 38,
"minutes": 30.20832
},
"longitude": {
"degrees": "-122",
"minutes": "5",
"seconds": 11.2704
}
},
"elevation": {
"units":"m"
},
"address": {
"county":"Napa"
},
}]
}]
}
Arthropod
There are two possible subtype values for type = arthro. The object structure for a single element of the record array depends upon the value for subtype. Permitted subtype values are: collection, pool.
Arthropod Collection (subtype = collection)
{
"type":"arthro",
"subtype":"collection",
"record":[{
"site":"SITE_CODE",
<"coordinates": {
"latitude": {
"degrees":"DEGREES",
<"minutes":"MINUTES",
<"seconds":"SECONDS">>
},
"longitude": {
"degrees":"DEGREES",
<"minutes":"MINUTES",
<"seconds":"SECONDS">>
}
},>
<"coordinate_precision":"(Exact|Unknown|Approximate|City|County)",>
<"identifiedby":[
"IDENTIFIED_BY",
...
<"IDENTIFIED_BY">
],>
"trap": {
<"number":"NUMBER_OF_TRAPS",>
"type":"TRAP_TYPE",
"nights":"TRAP_NIGHTS",
<"problem":"(Y|N|t|f|1|0)">
},
<"lure":"LURE_TYPE", | ["LURE_TYPE_1" , "LURE_TYPE_2"],>
"collectiondate": ({
"value": "COLLECTION_DATE",
"format": "(Y-M-D)"
} |
"COLLECTION_DATE"
),
<"countset":[{
"taxonomy": {
<"family":"FAMILY",>
<"genus":"GENUS",>
<"species":"SPECIES">
},
"sex": {
"female": {
<"mixed":"MIXED",>
<"unfed":"UNFED",>
<"gravid":"GRAVID",>
<"bloodfed":"BLOODFED">
},
<"male":"MALE",>
<"unknown":"UNKNOWN",>
<"eggs":"EGGS",>
<"larvae":"LARVAE",>
<"pupae":"PUPAE",>
}
},
{}],>
<"poolset": [{
"number": "POOL_NUMBER",
<"othersite": [({
"code":"OTHER_SITE_CODE",
"count":"COUNT"
},|
"SITE_CODE"
)],>
"taxonomy": {
<"family":"FAMILY",>
"genus":"GENUS",
"species":"SPECIES"
},
"sex":"(female|male|f|m|u|e|l|p)",
"condition":"(mixed|unfed|bloodfed|gravid)",
"count":"COUNT",
<"comments":"COMMENTS">
}, {
}],>
<"comments":"COMMENTS">
},
{}]
}
Example
{
"recordset":[{
"type": "arthro",
"subtype": "collection",
"record": [{
"site": "000001",
"coordinates": {
"latitude": "38.503472",
"longitude": "-122.086464"
},
"coordinate_precision":"Approximate",
"identifiedby": [
"foo",
"bar"
],
"trap": {
"number": 2,
"type": "co2",
"nights": 1
},
"lure":"CO2",
"collectiondate": "2012-04-01",
"countset": [{
"taxonomy": {
"genus": "cx",
"species": "tarsalis"
},
"sex": {
"female": 5,
"male": 1
}
}],
"comments": "This is a comment"
}, {
"site": "0",
"coordinates": {
"latitude": "38.503472",
"longitude": "-122.086464"
},
"coordinate_precision":"Unknown",
"identifiedby": [
"foo",
"bar"
],
"trap": {
"number": 2,
"type": "co2",
"nights": 1
},
"lure":["CO2", "Light"],
"collectiondate": "2012-04-01",
"poolset": [{
"number": 1,
"taxonomy": {
"genus": "culex",
"species": "tarsalis"
},
"sex": "f",
"condition": "mixed",
"count": 1
}],
"countset": [{
"taxonomy": {
"genus": "aedes"
},
"sex": {
"female": 5,
"male": 1
}
}, {
"taxonomy": {
"genus": "culex",
"species": "tarsalis"
},
"sex": {
"female": {
"unfed": 1,
"gravid": 1,
"bloodfed": 1
},
"male": 5
}
}
],
"comments": "This is a comment"
}, {
"site": "0",
"coordinates": {
"latitude": "38.503472",
"longitude": "-122.086464"
},
"identifiedby": [
"foo",
"bar"
],
"trap": {
"number": 2,
"type": "co2",
"nights": 1
},
"collectiondate": "2012-04-01",
"comments": "This is a comment"
}]
}]
}
Arthropod Pool (subtype = pool)
{
"type":"arthro",
"subtype":"pool",
"record":[{
"number":"POOL_NUMBER",
"site": ({
"code":"SITE_CODE",
<"other": [({
"code":"OTHER_SITE_CODE",
"count":"COUNT"
},|
"OTHER_SITE_CODE"
)]>
} | "SITE_CODE"),
"trap":"TRAP_TYPE",
<"lure":"LURE_TYPE", | ["LURE_TYPE_1" , "LURE_TYPE_2"],>
"collectiondate": ({
"value": "COLLECTION_DATE",
"format": "(Y-M-D)"
} |
"COLLECTION_DATE"
),
"taxonomy": {
<"family":"FAMILY",>
"genus":"GENUS",
"species":"SPECIES"
},
"sex":"(female|male|f|m)",
"condition":"(mixed|unfed|bloodfed|gravid)",
"count":"COUNT",
<"comments":"COMMENTS",>
"testset":[{
"testdate": ({
"value": "TEST_DATE",
"format": "(Y-M-D)"
} |
"TEST_DATE"
),
"method":"METHOD",
<"test_agency":"TEST_AGENCY_CODE",>
"targetset":[{
"target":"TARGET",
<"value":"VALUE",>
<"result":"(pending|negative|positive|other)",>
<"comments":"COMMENTS">
},
{}]
},
{}]
},
{}]
}
{
"recordset":[{
"type": "arthro",
"subtype": "pool",
"record": [{
"number": 0,
"site": 0,
"trap": "CO2",
"lure":"Light",
"collectiondate": "2012-07-10",
"taxonomy": {
"genus": "culex",
"species": "tarsalis"
},
"sex": "f",
"condition": "unfed",
"count": 50
}, {
"number": 2,
"site": 0,
"trap": "CO2",
"collectiondate": "2012-07-10",
"taxonomy": {
"genus": "culex",
"species": "tarsalis"
},
"sex": "f",
"condition": "mixed",
"count": 1
}, {
"number": 3,
"site": 1,
"trap": "CO2",
"lure":"Octenol",
"collectiondate": "2012-07-10",
"taxonomy": {
"genus": "culex",
"species": "tarsalis"
},
"sex": "f",
"condition": "mixed",
"count": 12
}, {
"number": 4,
"site": 1,
"trap": "NJLT",
"lure":["Octenol","CO2"],
"collectiondate": "2012-07-11",
"taxonomy": {
"genus": "culex",
"species": "anips"
},
"sex": "f",
"condition": "gravid",
"count": 20,
"testset": [{
"testdate": {
"value": "2012-07-11"
},
"method": "RAMP",
"test_agency":" DART",
"targetset": [{
"target": "WNV"
}, {
"target": "SLEV",
"result": "negative"
}
]
}
]
}, {
"number": 3,
"collectiondate": "2012-07-10",
"testset": [{
"testdate": {
"value": "2012-07-11"
},
"method": "RAMP",
"test_agency":" DART",
"targetset": [{
"target": "WNV",
"result": "positive"
}, {
"target": "WEEV",
"result": "negative"
}
]
}
]
}, {
"number": 5,
"site": {
"code": 0,
"other": [{
"code": 1,
"count": 1
}]
},
"trap": "CO2",
"collectiondate": "2012-07-10",
"taxonomy": {
"genus": "culex",
"species": "tarsalis"
},
"sex": "f",
"condition": "mixed",
"count": 2
}, {
"number": 6,
"site": {
"code": 1,
"other": [
0
]
},
"trap": "CO2",
"collectiondate": "2012-07-10",
"taxonomy": {
"genus": "culex",
"species": "tarsalis"
},
"sex": "m",
"condition": "mixed",
"count": 3
}]
}]
}
Sentinel
There are two possible subtype values for type = sentinel. The object structure for a single element of the record array depends upon the value for subtype. Permitted subtype values are: band, bleed.
Sentinel Band (subtype = band)
{
"type":"sentinel",
"subtype":"band",
"record":[{
"site":"SITE_CODE",
"year":"BAND_YEAR",
"comments":"COMMENTS",
"bandset":[({
"official":"OFFICIAL_BAND_NUMBER",
<"alternate":"LOCAL_BAND_NUMBER">
},|
"OFFICIAL_BAND_NUMBER",)
{}]
},
{}]
}
{
"recordset":[{
"type": "sentinel",
"subtype": "band",
"record": [{
"site": "543211",
"year": 2013,
"bandset": [
"1",
"2", {
"official": 3
}, {
"official": 4,
"alternate": 1234
}
]
}, {
"site": "543212",
"year": 2013,
"bandset": [
"5",
"6", {
"official": 7
}, {
"official": 8
}
]
}, {
"site": "543213",
"year": 2013,
"bandset": [
"9",
"10",
11,
12
]
}]
}]
}
Sentinel Bleed (subtype = bleed)
{
"type":"sentinel",
"subtype":"bleed",
"record":[{
"site":"SITE_CODE",
"year":"BAND_YEAR",
"collectiondate": ({
"value": "COLLECTION_DATE",
"format": "(Y-M-D)"
} |
"COLLECTION_DATE"
),
<"collectedby":[
"COLLECTED_BY",
...
"COLLECTED_BY"
],>
<"wholeblood":"(y|n|t|f|1|0)",>
<"comments":"COMMENTS",>
<"onlytests":"(y|n|t|f|1|0)",>
"bandset":[({
"official":"OFFICIAL_BAND_NUM",
<"testset":[{
"testdate": ({
"value": "TEST_DATE",
"format": "(Y-M-D)"
} |
"TEST_DATE"
),
"method":"METHOD",
"targetset":[{
"target":"TARGET",
<"value":"VALUE",>
<"result":"(pending|negative|positive|other)",>
<"comments":"COMMENTS">
},
{}]
},
{}]>
} |
"OFFICIAL_BAND_NUM"
),
{}]
},
{}]
}
{
"recordset":[{
"type": "sentinel",
"subtype": "bleed",
"record": [{
"site": "543211",
"year": 2013,
"collectiondate": "2013-03-03",
"collectedby": [
"snickers",
"milkyway"
],
"wholeblood": "false",
"comments": "some comments",
"bandset": [
1,
"2",
3,
"4"
]
}, {
"site": "543211",
"year": 2013,
"collectiondate": {
"format": "M/D/Y",
"value": "04/01/2013"
},
"collectedby": "babyruth",
"wholeblood": 0,
"comments": "more comments",
"bandset": [{
"official": 1
}, {
"official": "2"
},{
"official": 3
},
4
]
}, {
"site": "543211",
"year": 2013,
"collectiondate": {
"format": "M/D/Y",
"value": "04/02/2013"
},
"collectedby": "skittles",
"wholeblood": "false",
"comments": "more comments",
"bandset": [{
"official": 1,
"testset": [{
"testdate": "2013-04-03",
"method": "EIA",
"targetset": [{
"target": "WNV"
}, {
"target": "WEEV",
"result": "negative"
}, {
"target": "SLEV",
"result": "negative"
}]
}]
}, {
"official": "2",
"testset": [{
"testdate": "2013-04-03",
"method": "EIA",
"targetset": [{
"target": "WNV",
"result": "positive"
}, {
"target": "WEEV",
"result": "negative"
}, {
"target": "SLEV",
"result": "negative"
}]
}]
},{
"official": 3,
"testset": [{
"testdate": "2013-04-03",
"method": "EIA",
"targetset": [{
"target": "WNV",
"result": "negative"
}, {
"target": "WEEV",
"result": "negative"
}, {
"target": "SLEV",
"result": "negative"
}]
}]
}, {
"official": 4,
"testset": [{
"testdate": "2013-04-03",
"method": "EIA",
"targetset": [{
"target": "WNV",
"result": "negative"
}, {
"target": "WEEV",
"result": "negative"
}, {
"target": "SLEV",
"result": "negative"
}]
}]
}]
}]
}]
}
Export
Introduction
The VectorSurv Gateway (here-in called the Gateway) export web service provides local agencies the ability to pull a set of surveillance records based upon filters provided by the request. This service is primarily intended for consumption by local in-house applications.
Requirements
The Gateway export web service is secured and require authentication. Authentication is done by providing an Agency Token generated by the Gateway. To generate an Agency Token, your Gateway account must be an Agency Manager. If not, you will need to ask someone from your agency with Agency Manager access to generate you a token.
Agency tokens can be generated through the Agency Tokens item found in the My Agency section of the Settings menu. Each token is associated with the user who generated the token, the agency of the user and the privileges of the user. Therefore, any data exported will only comprise those surveillance records of the agency of the user who generated the token.
Conventions
The following conventions are used when describing the structure and format of the JSON-encoded export filters.
If a key-value pair is optional, the pair will be enclosed with the less-than (<) and greater-than (>) characters.
If a key can have one of several specified values, the possible values will be enclosed with parentheses ("(" and ")") and separated with a vertical pipe (|) character."pools": "(y|n|t|f|1|0)"
...
...
"collectiondate": {
"from": ({
"value": "FROM_DATE",
"format": "(Y-M-D)"
}| "FROM_DATE")
"to": ({
"value": "TO_DATE",
"format": "(Y-M-D)"
}| "TO_DATE")
},
The specifications below may not list all the possible values for a key. This is particularly true for the format key of date filters where it is best to check on the Gateway what date formats are available.
Upper-case strings are used to denote values provided by the request (filter parameters) or export data in the response.
"sample": "TEST_SAMPLE",
"method": "TEST_METHOD",
"target": "TEST_TARGET",
"result": "TEST_RESULT",
"value": "TEST_VALUE",
Basic Request Structure
The export web-service is a POST request with some parameters provided in the URL query and the export filter data JSON-encoded in a POST variable.
https://gateway.vectorsurv.org/ws.php?module=core&ppf=export.ws&output=json&token=TOKEN The POST request contains the variable export whose value is a JSON-encoded string of the filters to use when screening returned records.
Permitted user URL parameters are:
output
Determines the format used to encapsulate the response from the web service. Permitted values are: json (default), xml, html, text.
token
Agency token generated by the Gateway using the Agency Tokens tool. The JSON object to be passed to the web service through the export POST variable has the following structure.
The JSON object contains three keys.type
Indicates the type of surveillance data to export. Permitted values are: site, arthro, sentinel, carcass.
subtype
Required when type = arthro, sentinel or carcass. For type = arthro, values can be: collection, pool. For type = sentinel, values can be: band, bleed. For type = carcass, values can be: report, submission.
filter
An object whose key-value pairs screen the returned records to only those specified. In PHP, the export POST variable would look something like the following.
Basic Response Structure
It is strongly recommended that the URL parameter output be set to json or not be provided as JSON provides structure not found in the other output formats. This section assumes that the response is a JSON object.
The response object has the following structure.
If there are no errors or warnings, the respective key will not be present in the message object. If there are no errors AND warnings, the message object will not exist in the response.If the data object is not present, an error occurred in the export process.
Example
Example{
"message": {
"Warning": [
"No data matched the provided filter criteria. By relaxing the filter criteria, some data may match."
]
}
}
Specific Request/Response Structure
Surveillance Site
Request
Example Response{
"data": {
"SITE_CODE": {
"SITE_ID": {
"agency_code": "AGENCY_CODE",
"site_name": "SITE_NAME",
"elevation": {
"units": "UNITS",
"value": "ELEVATION"
},
"surroundings": [
"SURROUNDINGS",
...
"SURROUNDINGS"
],
"site_group": [
"SITE_GROUP",
...
"SITE_GROUP"
],
"pop_class": [
"POP_CLASS",
...
"POP_CLASS"
],
"coordinates": {
"current": {
"longitude": "LONGITUDE",
"latitude": "LATITUDE"
},
"initial": {
"longitude": "LONGITUDE",
"latitude": "LATITUDE"
}
},
"active": {
"start_date": {
"format": "DATE_FORMAT",
"value": "START_DATE"
},
"end_date": {
"format": "DATE_FORMAT",
"value": "END_DATE"
}
},
"revision": {
"add_date": {
"format": "DATE_FORMAT",
"value": "ADD_DATE"
},
"deactive_date": {
"format": "DATE_FORMAT",
"value": "DEACTIVE_DATE"
},
"comments": "COMMENTS"
},
"address": {
"primary": "PRIMARY_ADDRESS",
"secondary": "SECONDARY_ADDRESS",
"city": "CITY",
"postal": "POSTAL_CODE",
"region": "COUNTY_STATE_COUNTRY"
},
"comments": "COMMENTS"
},
...
"SITE_ID": {}
},
...
"SITE_CODE": {}
}
}
{
"data":{
"000000":{
"4828":{
"agency_code":"CVEC",
"site_name":"Center for Vectorborne Diseases, UC Davis",
"elevation":{
"units":"ft",
"value":"50.8529166666667"
},
"surroundings":[
"School"
],
"coordinates":{
"current":{
"longitude":"-121.764994",
"latitude":"38.532574"
},
"initial":{
"longitude":"-121.753533",
"latitude":"38.520256"
}
},
"active":{
"start_date":{
"format":"Y-m-d H:i:s",
"value":"1901-01-01 00:00:00"
},
"end_date":{
"format":"Y-m-d H:i:s",
"value":null
}
},
"revision":{
"add_date":{
"format":"Y-m-d H:i:s",
"value":"2012-04-27 12:59:30"
},
"deactive_date":{
"format":"Y-m-d H:i:s",
"value":null
}
},
"address":{
"primary":"VM3A",
"secondary":"One Shields Ave",
"city":"Davis",
"postal":"95616",
"region":"Yolo County (California, USA)"
}
}
}
}
}
Arthropod
Arthropod Collection (subtype = collection)
Request
{
"type": "arthro",
"subtype": "collection",
"filter": {
"collectiondate": {
"from": ({
"value": "FROM_DATE",
"format": "(Y-M-D)"
}| "FROM_DATE")
"to": ({
"value": "TO_DATE",
"format": "(Y-M-D)"
}| "TO_DATE")
},
"site": [
"SITE_CODE",
...
"SITE_CODE"
],
"traptype" [
"TRAP_TYPE",
...
"TRAP_TYPE"
],
"bioclass": [
"BIO_CLASS",
...
"BIO_CLASS"
],
"pools": "(y|n|t|f|1|0)"
}
}
{
"type": "arthro",
"subtype": "collection",
"filter": {
"collectiondate": {
"from": "2010-07-01",
"to": "2010-07-15"
},
"pools": "yes"
}
}
{
"data": {
"COLLECTION_ID": {
"surv_year": "SURVEILLANCE_YEAR",
"number": "AGENCY_COLLECTION_NUMBER",
"identified_by": [
"IDENTIFIED_BY",
...
"IDENTIFIED_BY"
],
"collection_date": {
"format": "DATE_FORMAT",
"value": "COLLECTION_DATE"
},
"site": {
"id": "SITE_ID",
"code": "SITE_CODE",
"name": "SITE_NAME",
"group": [
"SITE_GROUP",
...
"SITE_GROUP"
]
},
"coordinates": {
"longitude": "LONGITUDE",
"latitude": "LATITUDE"
},
"trap": {
"type": "TRAP_TYPE",
"number": "NUMBER_OF_TRAPS",
"nights": "NUMBER_OF_NIGHTS",
"problem": "TRAP_PROBLEM",
"lure":["LURE_TYPE","LURE_TYPE]
},
"lure":
"countset": [
{
"taxonomy": {
"TAXONOMIC_RANK": "TAXONOMIC_VALUE",
...
"TAXONOMIC_RANK": "TAXONOMIC_VALUE"
},
"sex": {
"male": "MALE_COUNT",
"female": {
"FEMALE_CONDITION": "FEMALE_CONDITION_COUNT",
...
"FEMALE_CONDITION": "FEMALE_CONDITION_COUNT"
}
}
},
...
{}
],
"poolset": {
"POOL_ID": {
"surv_year": "SURVEILLANCE_YEAR",
"number": "AGENCY_POOL_NUMBER",
"submission": {
"id": "SUBMISSION_ID",
"year": "YEAR_OF_SUBMISSION_NUMBER",
"number": "SUBMISSION_NUMBER"
},
"other_sites": [
{
"code": "OTHER_SITE_CODE",
"count": "OTHER_COUNT"
},
...
{}
],
"taxonomy": {
"TAXONOMIC_RANK": "TAXONOMIC_VALUE",
...
"TAXONOMIC_RANK": "TAXONOMIC_VALUE"
},
"sex": "SEX",
"condition": "CONDITION",
"count": "NUMBER_IN_POOL",
"comments": "COMMENTS"
},
...
{}
},
"comments": "COMMENTS"
},
...
"COLLECTION_ID": {}
}
}
{
"data": {
"714349":{
"surv_year":"2010",
"number":"1330",
"collection_date":{
"value": "2010-07-01",
"format": "Y-m-d"
},
"site":{
"code":"000200",
"name":"Mecca Fire Station",
"group":[
"COAV-IPS-CHIC",
"COAV-IPS-MOSQ",
"Upland"
]
},
"coordinates":{
"longitude":"-116.0",
"latitude":"33.0"
},
"trap":{
"type":"GRVD",
"number":"1",
"nights":"1",
"problem":false,
"lure": ["None"]
},
"countset":[{
"taxonomy":{
"species":"quinquefasciatus",
"genus":"culex"
},
"sex":{
"female":{
"gravid":"6"
}
}
}]
},
"714350":{
"surv_year":"2010",
"number":"1331",
"collection_date":{
"value": "2010-07-01",
"format": "Y-m-d"
},
"site":{
"code":"000204",
"name":"York",
"group":[
"COAV-IPS-CHIC",
"COAV-IPS-MOSQ",
"Mid Valley"
]
},
"coordinates":{
"longitude":"-116.0",
"latitude":"33.0"
},
"trap":{
"type":"GRVD",
"number":"1",
"nights":"1",
"problem":false,
"lure": ["CO2","Light"]
},
"countset":[
{
"taxonomy":{
"species":"tarsalis",
"genus":"culex"
},
"sex":{
"male":"1",
"female":{
"unfed":"4"
}
}
},
{
"taxonomy":{
"species":"quinquefasciatus",
"genus":"culex"
},
"sex":{
"male":"2",
"female":{
"unfed":"1"
}
}
}
],
"poolset":{
"201381":{
"surv_year":"2010",
"number":"2186",
"submission":{
"id":"3673",
"year":"2010",
"number":"17"
},
"taxonomy":{
"species":"quinquefasciatus",
"genus":"culex"
},
"sex":"female",
"count":"6",
"condition":"gravid"
}
}
}
}
}
Arthropod Pool (subtype = pool)
Request
{
"type": "arthro",
"subtype": "pool",
"filter": {
"collectiondate": {
"from": ({
"value": "FROM_DATE",
"format": "(Y-M-D)"
}| "FROM_DATE")
"to": ({
"value": "TO_DATE",
"format": "(Y-M-D)"
}| "TO_DATE")
},
"pool": {
"from": "FROM_POOL_NUM",
"to": "TO_POOL_NUM"
},
"site": [
"SITE_CODE",
...
"SITE_CODE"
],
"bioclass": [
"BIO_CLASS",
...
"BIO_CLASS"
],
"results": "(y|n|t|f|1|0)",
"method": [
"TEST_METHOD",
...
"TEST_METHOD"
],
"target": [
"TEST_TARGET",
...
"TEST_TARGET"
],
"status": [
"TEST_STATUS",
...
"TEST_STATUS"
]
}
}
{
"type": "arthro",
"subtype": "pool",
"filter": {
"collectiondate": {
"from": "2010-07-01",
"to": "2010-07-15"
},
"results": 1
}
}
{
"data": {
"POOL_ID": {
"surv_year": "SURVEILLANCE_YEAR",
"number": "AGENCY_POOL_NUMBER",
"collection_date": {
"format": "DATE_FORMAT",
"value": "COLLECTION_DATE"
},
"submission": {
"id": "SUBMISSION_ID",
"year": "YEAR_OF_SUBMISSION_NUMBER",
"number": "SUBMISSION_NUMBER"
},
"trap": "TRAP_TYPE",
"lure": ["LURE_TYPE","LURE_TYPE"],
"taxonomy": {
"TAXONOMIC_RANK": "TAXONOMIC_VALUE",
...
"TAXONOMIC_RANK": "TAXONOMIC_VALUE"
},
"sex": "SEX",
"condition": "CONDITION",
"count": "NUMBER_IN_POOL"
"site": {
"id": "SITE_ID",
"code": "SITE_CODE",
"name": "SITE_NAME",
"group": [
"SITE_GROUP",
...
"SITE_GROUP"
],
"other": [
{
"code": "OTHER_SITE_CODE",
"count": "OTHER_COUNT"
},
...
{}
]
},
"coordinates": {
"longitude": "LONGITUDE",
"latitude": "LATITUDE"
},
"comments": "COMMENTS",
"resultset": {
"TEST_TARGET": "POSITIVE?",
...
"TEST_TARGET": "POSITIVE?"
},
"testset": {
"POOL_TEST_ID": {
"test_date": {
"format": "DATE_FORMAT",
"value": "test_date"
},
"test_agency": "TEST_AGENCY_CODE",
"method": "TEST_METHOD",
"target": "TEST_TARGET",
"result": "TEST_RESULT",
"value": "TEST_VALUE",
"comments": "TEST_COMMENTS"
}
...
"POOL_TEST_ID": {}
}
},
...
"POOL_ID": {}
}
}
{
"data":{
"201396":{
"number":"2159",
"surv_year":"2010",
"submission":{
"id":"3673",
"year":"2010",
"number":"17"
},
"taxonomy":{
"species":"quinquefasciatus",
"genus":"culex"
},
"sex":"female",
"count":"46",
"site":{
"code":"000344",
"group":[
"COAV-IPS-MOSQ",
"Upper Valley"
],
"name":"La Quinta Yard"
},
"coordinates":{
"longitude":"-116.0",
"latitude":"33.0"
},
"trap":"GRVD",
"lure": ["Unspecified" ],
"collection_date":{
"format":"Y-m-d",
"value":"2010-07-01"
},
"condition":"mixed",
"testset":{
"501558":{
"test_date":{
"format":"Y-m-d",
"value":"2010-07-08"
},
"test_agency":"CVEC",
"method":"RTPCR",
"target":"SLEV",
"result":"Negative"
},
"501557":{
"test_date":{
"format":"Y-m-d",
"value":"2010-07-08"
},
"test_agency":"CVEC",
"method":"RTPCR",
"target":"WEEV",
"result":"Negative"
},
"501556":{
"test_date":{
"format":"Y-m-d",
"value":"2010-07-08"
},
"test_agency":"CVEC",
"method":"RTPCR",
"target":"WNV",
"result":"Negative"
}
}
},
"201532":{
"number":"2160",
"surv_year":"2010",
"submission":{
"id":"3673",
"year":"2010",
"number":"17"
},
"taxonomy":{
"species":"quinquefasciatus",
"genus":"culex"
},
"sex":"female",
"count":"50",
"site":{
"code":"000344",
"group":[
"COAV-IPS-MOSQ",
"Upper Valley"
],
"name":"La Quinta Yard"
},
"coordinates":{
"longitude":"-116.0",
"latitude":"33.0"
},
"trap":"CO2",
"lure": ["CO2","Light" ],
"collection_date":{
"format":"Y-m-d",
"value":"2010-07-01"
},
"condition":"unfed",
"testset":{
"501561":{
"test_date":{
"format":"Y-m-d",
"value":"2010-07-08"
},
"test_agency":"CVEC",
"method":"RTPCR",
"target":"SLEV",
"result":"Negative"
},
"501560":{
"test_date":{
"format":"Y-m-d",
"value":"2010-07-08"
},
"test_agency":"CVEC",
"method":"RTPCR",
"target":"WEEV",
"result":"Negative"
},
"501559":{
"test_date":{
"format":"Y-m-d",
"value":"2010-07-08"
},
"test_agency":"CVEC",
"method":"RTPCR",
"target":"WNV",
"result":"Negative"
}
}
}
}
}
Sentinel
Sentinel Band (subtype = band)
Request
{
"type": "sentinel",
"subtype": "band",
"filter": {
"year": [
"BAND_YEAR",
...
"BAND_YEAR"
],
"flock": [
"FLOCK_SITE",
...
"FLOCK_SITE"
],
"bleeds": "(y|n|t|f|1|0)"
}
}
{
"type": "sentinel",
"subtype": "band",
"filter": {
"year": "2011",
"flock": [
"000327",
"000539"
],
"bleeds": "t"
}
}
{
"data": {
"BAND_ID": {
"year": "BAND_YEAR",
"number": {
"official": "OFFICIAL_BAND_NUMBER",
"alternate": "LOCAL_BAND_NUMBER"
},
"flock": {
"id": "FLOCK_ID",
"year": "FLOCK_YEAR",
"site": {
"id": "SITE_ID",
"code": "SITE_CODE",
"name": "SITE_NAME",
"group": [
"SITE_GROUP",
...
"SITE_GROUP"
]
},
"coordinates": {
"longitude": "LONGITUDE",
"latitude": "LATITUDE"
}
},
"seroconversion": {
"TEST_TARGET": {
"format": "DATE_FORMAT",
"value": "SEROCONVERSION_DATE"
},
...
"TEST_TARGET": {}
}
"bleedset": {
"BAND_BLEED_ID": {
"year": "FLOCK_BLEED_YEAR",
"number": "FLOCK_BLEED_NUMBER",
"collection_date": {
"format": "DATE_FORMAT",
"value": "COLLECTION_DATE"
},
"whole_blood": "WHOLE_BLOOD?",
"worksheet": "WORKSHEET?",
"tested": "TESTED?",
"coordinates": {
"longitude": "LONGITUDE",
"latitude": "LATITUDE"
},
"collected_by": [
"COLLECTED_BY",
...
"COLLECTED_BY"
],
"comments": {
"band": "BAND_BLEED_COMMENTS",
"flock": "FLOCK_BLEED_COMMENTS"
}
},
...
"BAND_BLEED_ID": {}
}
},
...
"BAND_ID": {}
}
}
{
"data":{
"19150":{
"year":"2011",
"number":{
"official":"1181"
},
"flock":{
"id":"1805",
"year": "2011",
"site":{
"code":"000327",
"name":"DHS Bubbling Wells and 18th",
"group":[
"COAV-IPS-CHIC"
]
},
"coordinates":{
"longitude":"-116.484575",
"latitude":"33.917922"
}
},
"bleedset":{
"224516":{
"year":"2011",
"number":"12",
"collection_date":{
"format":"Y-m-d",
"value":"2011-04-04"
},
"whole_blood":false,
"worksheet":false,
"tested":true,
"coordinates":{
"longitude":"-116.484575",
"latitude":"33.917922"
}
},
}
},
"19309":{
"year":"2011",
"number":{
"official":"1340"
},
"flock":{
"id":"1809",
"year": "2011",
"site":{
"code":"000539",
"name":"Avenue 54 and Jackson",
"group":[
"COAV-IPS-CHIC"
]
},
"coordinates":{
"longitude":"-116.218393",
"latitude":"33.656714"
}
},
"bleedset":{
"244443":{
"year":"2011",
"number":"181",
"collection_date":{
"format":"Y-m-d",
"value":"2011-10-17"
},
"whole_blood":false,
"worksheet":false,
"tested":true,
"coordinates":{
"longitude":"-116.218393",
"latitude":"33.656714"
}
},
"245436":{
"year":"2011",
"number":"193",
"collection_date":{
"format":"Y-m-d",
"value":"2011-10-31"
},
"whole_blood":false,
"worksheet":false,
"tested":true,
"coordinates":{
"longitude":"-116.218393",
"latitude":"33.656714"
}
}
}
}
}
}
Sentinel Bleed (subtype = bleed)
Request
{
"type": "sentinel",
"subtype": "bleed",
"filter": {
"year": [
"BAND_YEAR",
...
"BAND_YEAR"
],
"flock": [
"FLOCK_SITE",
...
"FLOCK_SITE"
],
"collectiondate": {
"from": ({
"value": "FROM_DATE",
"format": "(Y-M-D)"
}| "FROM_DATE")
"to": ({
"value": "TO_DATE",
"format": "(Y-M-D)"
}| "TO_DATE")
},
"results": "(y|n|t|f|1|0)",
"method": [
"TEST_METHOD",
...
"TEST_METHOD"
],
"target": [
"TEST_TARGET",
...
"TEST_TARGET"
],
"status": [
"TEST_STATUS",
...
"TEST_STATUS"
]
}
}
{
"type": "sentinel",
"subtype": "bleed",
"filter": {
"year": [
2011
],
"flock": [
"000201"
],
"results": 1,
"status": "Confirmed"
}
}
{
"data": {
"FLOCK_BLEED_ID": {
"year": "FLOCK_BLEED_YEAR",
"number": "FLOCK_BLEED_NUMBER",
"collection_date": {
"format": "DATE_FORMAT",
"value": "COLLECTION_DATE"
},
"whole_blood": "WHOLE_BLOOD?",
"worksheet": "WORKSHEET?",
"bandset": {
"BAND_BLEED_ID": {
"band": {
"id": "BAND_ID",
"year": "BAND_YEAR",
"official": "OFFICIAL_BAND_NUMBER",
"alternate": "LOCAL_BAND_NUMBER"
},
"status": "BAND_BLEED_STATUS",
"comments": "BAND_BLEED_COMMENTS",
"seroconversion": {
"TEST_TARGET": {
"format": "DATE_FORMAT",
"value": "SEROCONVERSION_DATE"
},
...
"TEST_TARGET": {}
},
"testset": {
"BAND_BLEED_TEST_ID": {
"test_date": {
"format": "DATE_FORMAT",
"value": "TEST_DATE"
},
"test_agency": "TEST_AGENCY",
"method": "TEST_METHOD",
"target": "TEST_TARGET",
"result": "TEST_RESULT",
"value": "TEST_VALUE",
"comments": "TEST_COMMENTS"
},
...
"BAND_BLEED_TEST_ID": {}
}
},
...
"BAND_BLEED_ID": {}
},
"flock": {
"id": "FLOCK_ID",
"year": "FLOCK_YEAR",
"site": {
"id": "SITE_ID",
"code": "SITE_CODE",
"name": "SITE_NAME",
"group": [
"SITE_GROUP",
...
"SITE_GROUP"
],
}
},
"coordinates": {
"longitude": "LONGITUDE",
"latitude": "LATITUDE"
},
"collected_by": [
"COLLECTED_BY",
...
"COLLECTED_BY"
],
"comments": "FLOCK_BLEED_COMMENTS"
},
...
"FLOCK_BLEED_ID": {}
}
}
{
"data":{
"30241":{
"year":"2011",
"number":"126",
"collection_date":{
"format":"Y-m-d",
"value":"2011-08-22"
},
"whole_blood":false,
"worksheet":false,
"bandset":{
"238189":{
"band":{
"id":"19208",
"year":"2011",
"official":"1239"
},
"tested":true,
"testset":{
"814821":{
"test_date":{
"format":"Y-m-d",
"value":"2011-08-30"
},
"test_agency":"VBDS",
"method":"WB",
"target":"WNV",
"result":"Confirmed"
}
}
}
},
"flock":{
"id":"1810",
"year":"2011",
"site":{
"code":"000201",
"name":"Limon\/Sanchez Mkt\/Thermal Hotel\/Cocopah",
"group":[
"COAV-IPS-CHIC",
"Mid Valley"
]
}
},
"coordinates":{
"longitude":"-116.136049",
"latitude":"33.634805"
}
},
"30467":{
"year":"2011",
"number":"138",
"collection_date":{
"format":"Y-m-d",
"value":"2011-09-06"
},
"whole_blood":false,
"worksheet":false,
"bandset":{
"239926":{
"band":{
"id":"19202",
"year":"2011",
"official":"1233"
},
"tested":true,
"testset":{
"819215":{
"test_date":{
"format":"Y-m-d",
"value":"2011-09-14"
},
"test_agency":"VBDS",
"method":"WB",
"target":"WNV",
"result":"Confirmed"
}
}
},
"239925":{
"band":{
"id":"19203",
"year":"2011",
"official":"1234"
},
"tested":true,
"testset":{
"819216":{
"test_date":{
"format":"Y-m-d",
"value":"2011-09-14"
},
"test_agency":"VBDS",
"method":"WB",
"target":"WNV",
"result":"Confirmed"
}
}
},
"239921":{
"band":{
"id":"19207",
"year":"2011",
"official":"1238"
},
"tested":true,
"testset":{
"819217":{
"test_date":{
"format":"Y-m-d",
"value":"2011-09-14"
},
"test_agency":"VBDS",
"method":"WB",
"target":"WNV",
"result":"Confirmed"
}
}
}
},
"flock":{
"id":"1810",
"year":"2011",
"site":{
"code":"000201",
"name":"Limon\/Sanchez Mkt\/Thermal Hotel\/Cocopah",
"group":[
"COAV-IPS-CHIC","Mid Valley"
]
}
},
"coordinates":{
"longitude":"-116.136049",
"latitude":"33.634805"
}
},
}
}
Carcass
Unlike all other values for type, carcass is not constrained to the agency of the web service token. So, specifying a "spatial" filter (zipcode, city, county) is encouraged.
Carcass Report (subtype = report)
Request
{
"type": "carcass",
"subtype": "report",
"filter": {
"reportdate": {
"from": ({
"value": "FROM_DATE",
"format": "(Y-M-D)"
}| "FROM_DATE")
"to": ({
"value": "TO_DATE",
"format": "(Y-M-D)"
}| "TO_DATE")
},
"zipcode": [
"ZIP_CODE",
...
"ZIP_CODE"
],
"city": [
"CITY",
...
"CITY"
],
"county": [
"COUNTY",
...
"COUNTY"
],
"species": [
"SPECIES",
...
"SPECIES"
],
"condition": [
"CONDITION",
...
"CONDITION"
],
"submissions": "(y|n|t|f|1|0)"
}
}
{
"type": "carcass",
"subtype": "report",
"filter": {
"reportdate": {
"from": "2011-06-01",
"to": "2011-06-01"
},
"county": [
"Kern",
"RIVERSIDE"
],
"submissions": 1
}
}
{
"data": {
"REPORT_ID": {
"report_date": {
"format": "DATE_FORMAT",
"value": "REPORT_DATE"
},
"parent": "PARENT_REPORT_ID",
"caller": {
"name": "CALLER_NAME",
"phone": {
"primary": {
"number": "PHONE_NUMBER",
"ext": "EXTENSION"
},
"secondary": {
"number": "PHONE_NUMBER",
"ext": "EXTENSION"
}
},
"email": "EMAIL_ADDRESS"
},
"coordinates": {
"longitude": "LONGITUDE",
"latitude": "LATITUDE"
},
"address": {
"primary": "PRIMARY_ADDRESS",
"secondary": "SECONDARY_ADDRESS",
"city": "CITY",
"county": "COUNTY",
"postal": "POSTAL",
"intersection": "INTERSECTION"
},
"carcass": {
"count": "NUMBER_OF_CARCASSES",
"street_sidewalk": "ON_STREET_OR_SIDEWALK?",
"species": "CARCASS_SPECIES",
"condition": "CARCASS_CONDITION"
}
"comments": "COMMENTS",
"submission": {
"BIRD_ID": {
"number": "DEAD_BIRD_NUMBER",
"agency": "SUBMITTING_AGENCY",
"result": "WNV_TEST_RESULT"
},
...
"BIRD_ID": {}
}
},
...
"REPORT_ID": {}
}
}
{
"data":{
"546406":{
"report_date":{
"format":"Y-m-d H:i:s",
"value":"2011-06-01 08:04:00"
},
"caller":{
"name":"Jane Doe",
"phone":{
"primary":{
"number":"5555555555"
},
"secondary":{
"number":"5555551234"
}
},
"email":"no@thanks"
},
"coordinates":{
"longitude":"-117.00000000000000",
"latitude":"33.000000000000000"
},
"address":{
"primary":"1600 Pennsylvania Ave",
"city":"Riverside",
"county":"Riverside",
"postal":"92508",
"intersection":"Road A and Road Z"
},
"carcass":{
"count":"1",
"street_sidewalk":false,
"species":"Say's Phoebe",
"condition":"Dead Less Than 24 Hours"
},
"comments":"the bird is in a bag on the porch"
},
"546445":{
"report_date":{
"format":"Y-m-d H:i:s",
"value":"2011-06-01 12:49:00"
},
"caller":{
"name":"John",
"phone":{
"primary":{
"number":"5551235555"
}
}
},
"coordinates":{
"longitude":"-118.00000000000000",
"latitude":"35.00000000000000"
},
"address":{
"primary":"1010 Somewhere Dr",
"secondary":"Neither here nor there",
"city":"Bakersfield",
"county":"Kern",
"postal":"93306",
"intersection":"Neither here nor there"
},
"carcass":{
"count":"1",
"street_sidewalk":false,
"species":"Black-headed Grosbeak",
"condition":"Dead Less Than 24 Hours"
},
"comments":"Report source: VectorSurv Gateway\r\nAgency: Kern MVCD (KERN)\r\nUser: rtakahashi\r\nthe Jameson center, please go to the front office and ask for the bird"
},
"546455":{
"report_date":{
"format":"Y-m-d H:i:s",
"value":"2011-06-01 21:21:00"
},
"caller":{
"name":"No Thanks",
"phone":{
"primary":{
"number":"1235555555"
}
},
"email":"blackhole@no"
},
"coordinates":{
"longitude":"-119.00000000000000",
"latitude":"35.00000000000000"
},
"address":{
"primary":"1503 Anywhere Street",
"secondary":"Someplace off somewhere else",
"city":"Bakersfield",
"county":"Kern",
"postal":"93314",
"intersection":"Someplace off somewhere else"
},
"carcass":{
"count":"1",
"street_sidewalk":false,
"species":"European Starling",
"condition":"Dead Less Than 24 Hours"
},
"comments":"Report source: VectorSurv Gateway\nAgency: Kern MVCD (KERN)\nUser: rtakahashi\nBagged bird will be on front porch with a bowl placed over top of it. Bird is actually an immature European Starling",
"submission":{
"36511":{
"number":"11-839",
"agency":"Kern MVCD",
"result":"Negative"
}
}
}
}
}
Carcass Submission (subtype = submission)
Request
{
"type": "carcass",
"subtype": "submission",
"filter": {
"reportdate": {
"from": ({
"value": "FROM_DATE",
"format": "(Y-M-D)"
}| "FROM_DATE")
"to": ({
"value": "TO_DATE",
"format": "(Y-M-D)"
}| "TO_DATE")
},
"zipcode": [
"ZIP_CODE",
...
"ZIP_CODE"
],
"city": [
"CITY",
...
"CITY"
],
"county": [
"COUNTY",
...
"COUNTY"
],
"species": [
"SPECIES",
...
"SPECIES"
],
"condition": [
"CONDITION",
...
"CONDITION"
],
"results": "(y|n|t|f|1|0)",
"sample": [
"SAMPLE",
...
"SAMPLE"
],
"method": [
"TEST_METHOD",
...
"TEST_METHOD"
],
"status": [
"TEST_STATUS",
...
"TEST_STATUS"
]
}
}
{
"type": "carcass",
"subtype": "submission",
"filter": {
"reportdate": {
"from": "2011-06-01",
"to": "2011-06-01"
},
"county": [
"Kern",
"RIVERSIDE"
],
"results": 1
}
}
{
"data": {
"BIRD_ID": {
"number": "DEAD_BIRD_NUMBER",
"agency": "SUBMITTING_AGENCY",
"report": {
"value": "REPORT_ID",
"parent": "PARENT_REPORT_ID"
},
"report_date": {
"format": "DATE_FORMAT",
"value": "REPORT_DATE"
},
"caller": {
"name": "CALLER_NAME",
"phone": {
"primary": {
"number": "PHONE_NUMBER",
"ext": "EXTENSION"
},
"secondary": {
"number": "PHONE_NUMBER",
"ext": "EXTENSION"
}
},
"email": "EMAIL_ADDRESS"
},
"coordinates": {
"longitude": "LONGITUDE",
"latitude": "LATITUDE"
},
"address": {
"primary": "PRIMARY_ADDRESS",
"secondary": "SECONDARY_ADDRESS",
"city": "CITY",
"county": "COUNTY",
"postal": "POSTAL",
"intersection": "INTERSECTION"
},
"carcass": {
"count": "NUMBER_OF_CARCASSES",
"street_sidewalk": "ON_STREET_OR_SIDEWALK?",
"species": "CARCASS_SPECIES",
"condition": "CARCASS_CONDITION"
}
"comments": "COMMENTS",
"result": "WNV_TEST_RESULT"
"testset": {
"BIRD_TEST_ID": {
"test_agency": "TEST_AGENCY",
"test_date": {
"format": "DATE_FORMAT",
"value": "TEST_DATE"
},
"sample": "TEST_SAMPLE",
"method": "TEST_METHOD",
"target": "TEST_TARGET",
"result": "TEST_RESULT",
"value": "TEST_VALUE",
"comments": "TEST_COMMENTS"
},
...
"BIRD_TEST_ID": {}
}
},
...
"BIRD_ID": {}
}
}
{
"data":{
"36504":{
"number":"11-832",
"agency":"Riverside Public Services",
"report":{
"value":"546406"
},
"report_date":{
"format":"Y-m-d H:i:s",
"value":"2011-06-01 08:04:00"
},
"caller":{
"name":"Jane Doe",
"phone":{
"primary":{
"number":"5555555555"
},
"secondary":{
"number":"5555551234"
}
},
"email":"no@thanks"
},
"coordinates":{
"longitude":"-117.00000000000000",
"latitude":"33.000000000000000"
},
"address":{
"primary":"1600 Pennsylvania Ave",
"city":"Riverside",
"county":"Riverside",
"postal":"92508",
"intersection":"Road A and Road Z"
},
"carcass":{
"count":"1",
"street_sidewalk":false,
"species":"Say's Phoebe",
"condition":"Dead Less Than 24 Hours"
},
"comments":"the bird is in a bag on the porch",
"result":"Negative",
"testset":{
"39656":{
"test_agency":"Center for Vector Borne Diseases (UC Davis)",
"test_date":{
"value":"2011-06-08",
"format":"Y-m-d"
},
"sample":"Kidney Sample",
"method":"RT-PCR",
"target":"WNV",
"result":"Negative"
}
}
},
"36510":{
"number":"11-838",
"agency":"Kern MVCD",
"report":{
"value":"546445"
},
"report_date":{
"format":"Y-m-d H:i:s",
"value":"2011-06-01 12:49:00"
},
"caller":{
"name":"John",
"phone":{
"primary":{
"number":"5551235555"
}
}
},
"coordinates":{
"longitude":"-118.00000000000000",
"latitude":"35.00000000000000"
},
"address":{
"primary":"1010 Somewhere Dr",
"secondary":"Neither here nor there",
"city":"Bakersfield",
"county":"Kern",
"postal":"93306",
"intersection":"Neither here nor there"
},
"carcass":{
"count":"1",
"street_sidewalk":false,
"species":"Black-headed Grosbeak",
"condition":"Dead Less Than 24 Hours"
},
"comments":"Report source: VectorSurv Gateway\r\nAgency: Kern MVCD (KERN)\r\nUser: rtakahashi\r\nthe Jameson center, please go to the front office and ask for the bird",
"result":"Negative",
"testset":{
"39727":{
"test_agency":"Center for Vector Borne Diseases (UC Davis)",
"test_date":{
"value":"2011-06-15",
"format":"Y-m-d"
},
"sample":"Kidney Sample",
"method":"RT-PCR",
"target":"WNV",
"result":"Negative"
}
}
},
"36511":{
"number":"11-839",
"agency":"Kern MVCD",
"report":{
"value":"546455"
},
"report_date":{
"format":"Y-m-d H:i:s",
"value":"2011-06-01 21:21:00"
},
"caller":{
"name":"No Thanks",
"phone":{
"primary":{
"number":"1235555555"
}
},
"email":"blackhole@no"
},
"coordinates":{
"longitude":"-119.00000000000000",
"latitude":"35.00000000000000"
},
"address":{
"primary":"1503 Anywhere Street",
"secondary":"Someplace off somewhere else",
"city":"Bakersfield",
"county":"Kern",
"postal":"93314",
"intersection":"Someplace off somewhere else"
},
"carcass":{
"count":"1",
"street_sidewalk":false,
"species":"European Starling",
"condition":"Dead Less Than 24 Hours"
},
"comments":"Report source: VectorSurv Gateway\nAgency: Kern MVCD (KERN)\nUser: rtakahashi\nBagged bird will be on front porch with a bowl placed over top of it. Bird is actually an immature European Starling",
"result":"Negative",
"testset":{
"39728":{
"test_agency":"Center for Vector Borne Diseases (UC Davis)",
"test_date":{
"value":"2011-06-15",
"format":"Y-m-d"
},
"sample":"Kidney Sample",
"method":"RT-PCR",
"target":"WNV",
"result":"Negative"
}
}
}
}
}
Pesticide Application and Resistance Testing Import
Introduction
The Pesticide Application and Resistance Testing (here-in called PART) import web service provides local agencies the ability to import new and update existing records. This service is primarily intended for consumption by local in-house applications.
Requirements
The PART import web service is secured and require authentication. Authentication is done by providing an Agency Token generated by PART. To generate an Agency Token, your PART account must be an Agency Manager. If not, you will need to ask someone from your agency with Agency Manager access to generate you a token.
Agency tokens can be generated through the Agency Tokens item found in the My Agency section of the Settings menu. Each token is associated with the user who generated the token, the agency of the user and the privileges of the user. Therefore, any data imported is done as the user and agency who generated the token.
Conventions
The following conventions are used when describing the structure and format of the JSON-encoded import data.
If a key-value pair is optional, the pair will be enclosed with the less-than (<) and greater-than (>) characters.
<"name":"SOURCE_NAME",>
...
...
"coordinates": {
"latitude": {
"degrees":"DEGREES",
<"minutes":"MINUTES",
<"seconds":"SECONDS">>
},
"longitude": {
"degrees":"DEGREES",
<"minutes":"MINUTES",
<"seconds":"SECONDS">>
}
},
<"unit":"(lb|oz|g|kg)",>
...
...
<"elevation": ({
"unit":"(m|ft)",
"value":"(ELEVATION|auto)"
} |
"(ELEVATION|auto)",>
The specifications below may not list all the possible values for a key. This is particularly true for the format key of date values where it is best to check on the PART what date formats are available.
Upper-case strings are used to denote values provided by the request.
Basic Request Structure
The import web-service is a POST request with some parameters provided in the URL query and the import data JSON-encoded in a POST variable.
https://gateway.vectorsurv.org/ws.php?module=core&ppf=import.ws&output=json&token=TOKEN The POST request contains the variable insert whose value is a JSON-encoded string of the data to be imported into PART.
Permitted user URL parameters are:
output
Determines the format used to encapsulate the response from the web service. Permitted values are: json (default), xml, html, text.
token
Agency token generated by PART using the Agency Tokens tool The JSON object to be passed to the web service through the insert POST variable has the following structure.
The JSON object contains one key recordset.recordset
must an array of one or more objects Each element of the recordset array is an object comprised of three keys.
type
Indicates the type of recordset. This is used to direct how the recordset is processed. Permitted values are: source, application, equipment, mix.
record
must be an array of one or more objects Since the recordset and record variables are arrays of objects, it is possible to import many recordsets of many records in one call to the import web service.
In PHP, the insert POST variable would look like the following.
Spatial information such as point sources (points), truck routes or flight paths (linestrings), areas of application (polygons) must be in one of the following permitted formats:GeoJSON
Point:
Linestring: Polygon no holes:"shape": {
"type": "Polygon",
"coordinates": [
[ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ]
]
}
"shape": {
"type": "Polygon",
"coordinates": [
[ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ],
[ [100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8], [100.2, 0.2] ]
]
}
"shape": "01030000000100000005000000000000000000000000000000000000000000000000000000000000000000F03F000000000000F03F000000000000F03F000000000000F03F000000000000000000000000000000000000000000000000"
Regardless of the format, the spatial information must be in the WGS84 coordinate system (the default used by all GPS units).
Updating existing records require the presence of the key id. The id key value is provided by PART's Export Web service and is guaranteed to be unique in PART. Without the id key, the record is treated as a new record. If the id key value is invalid (or not found), the record is skipped with an error message.
Response Structure
It is strongly recommended that the URL parameter output be set to json or not be provided as JSON provides structure not found in the other output formats. This section assumes that the response is a JSON object.
The response object has the following structure.
Though there are three keys in the structure, the actual response to a web service request may contain one, two or all three keys. If there are no errors in the processing of the web service request, the response will not have the Error key. The same is true for the other keys.Example
{
"Error": [
"(Recordset 1, Record 1) The value provided for \"code\" key does not match the required format: ######.",
"(Recordset 5) Attribute \"type\" missing from "recordset" key.",
"(Recordset 6) Mising \"record\" key from recordset."
],
"Success": [
"(Recordset 2) The import of the recordset completed successfully.",
"(Recordset 3) The import of the recordset completed successfully.",
"(Recordset 4) The import of the recordset completed successfully."
]
}
Specific Request Structure
Application Source
The object structure for an element of the record array looks like the following.
{
"type":"source",
"record":[{
<"id":"ID",>
"code":"SOURCE_CODE",
"shape" : "SOURCE_SHAPE",
<"name":"SOURCE_NAME",>
<"address": {
"primary":"PRIMARY",
<"secondary":"SECONDARY",>
"city":"CITY",
"postal":"POSTAL",
"county":"COUNTY",
"state":"STATE",
"country":"COUNTRY"
},>
<"comments":"COMMENTS">
},
{}]
}
Pesticide Application
The object structure for an element of the record array looks like the following.
{
"type": "application",
"record": [{
<"id": "ID",>
"source": "SOURCE_CODE",
"purpose": "(Adulticide|Herbicide|Larvicide)",
"equipment": "EQUIPMENT_CODE",
"datetime":({
"start": ({
"value": "START_DATETIME",
"format": "Y-m-d H:i:s"
} |
"START_DATETIME"
),
"end": ({
"value": "END_DATETIME",
"format": "Y-m-d H:i:s"
} |
"END_DATETIME"
)
} | {
"start": ({
"value": "START_DATETIME",
"format": "Y-m-d H:i:s"
} |
"START_DATETIME"
),
"duration": "DURATION_SECONDS"
}),
"technician": "CERT_NUM",
"mix": {
"code": "MIX_CODE",
"quantity": {
"value": "QUANTITY",
"unit": "(lb|oz|cup|gal|l|ml|g|kg)"
},
},
"area": {
"value": "APPLIED_AREA",
"unit": "(ft|yard|acre|mile|m|km)"
},
<"description":"DESCRIPTION">
},
{}]
}
Technician
The object structure for an element of the record array looks like the following:
{
"type": "technician",
"record": [{
<"id": "ID",>
"first_name": "FIRST_NAME",
"last_name": "LAST_NAME",
"cert_num": "CERT_NUM"
},
{}]
}
Pesticide Mix
The object structure for an element of the record array looks like the following:
{
"type": "mix",
"record": [{
<"id": "ID",>
"code": "MIX_CODE",
<"description": "DESCRIPTION",>
"components": [{
"type": "(diluent|product)",
("diluent": "(Water|Acetone|BVA13|Mosquito Fish)",|
"product": "CDPR_REGISTRATION_NUM",)
"quantity": {
"value": "QUANTITY",
"unit": "(lb|oz|cup|gal|l|ml|g|kg)"
}
}]
},
{}]
}
Equipment
The object structure for an element of the record array looks like the following.
{
"type": "equipment",
"record": [{
<"id": "ID",>
"code": "EQUIPMENT_CODE",
<"manufacturer": "MANUFACTURER",>
<"model": "MODEL",>
<"serial": "SERIAL_NUMBER",>
<"description": "DESCRIPTION",>
},
{}]
}
Pesticide Application and Resistance Testing Export
Introduction
The Pesticide Application and Resistance Testing (here-in called PART) export web service provides local agencies the ability to pull a set of pesticide records based upon filters provided by the request. This service is primarily intended for consumption by local in-house applications.
Requirements
The PART export web service is secured and require authentication. Authentication is done by providing an Agency Token generated by PART. To generate an Agency Token, your PART account must be an Agency Manager. If not, you will need to ask someone from your agency with Agency Manager access to generate you a token.
Agency tokens can be generated through the Agency Tokens item found in the My Agency section of the Settings menu. Each token is associated with the user who generated the token, the agency of the user and the privileges of the user. Therefore, any data exported will only comprise those surveillance records of the agency of the user who generated the token.
Conventions
The following conventions are used when describing the structure and format of the JSON-encoded export filters.
If a key-value pair is optional, the pair will be enclosed with the less-than (<) and greater-than (>) characters.
<"name":"SOURCE_NAME",>
...
If a key can have one of several specified values, the possible values will be enclosed with parentheses ("(" and ")") and separated with a vertical pipe (|) character.
...
<"units":"(lb|oz|g|kg)",>
...
...
"applicationdate": {
"from": ({
"value": "FROM_DATE",
"format": "(Y-M-D)"
}| "FROM_DATE")
"to": ({
"value": "TO_DATE",
"format": "(Y-M-D)"
}| "TO_DATE")
},
The specifications below may not list all the possible values for a key. This is particularly true for the format key of date filters where it is best to check on the Gateway what date formats are available.
Upper-case strings are used to denote values provided by the request (filter parameters) or export data in the response.
Basic Request Structure
The export web-service is a POST request with some parameters provided in the URL query and the export filter data JSON-encoded in a POST variable.
https://gateway.vectorsurv.org/ws.php?module=core&ppf=export.ws&output=json&token=TOKEN The POST request contains the variable export whose value is a JSON-encoded string of the filters to use when screening returned records.
Permitted user URL parameters are:
output
Determines the format used to encapsulate the response from the web service. Permitted values are: json (default), xml, html, text.
token
Agency token generated by PART using the Agency Tokens tool. The JSON object to be passed to the web service through the export POST variable has the following structure.
The JSON object contains three keys.type
Indicates the type of pesticide data to export. Permitted values are: source, application, equipment, mix.
filter
An object whose key-value pairs screen the returned records to only those specified. In PHP, the export POST variable would look something like the following.
$_POST['export'] = '{"type":"TYPE","filter":{FILTER,FILTER}}';
Spatial information such as point sources (points), truck routes or flight paths (linestrings), areas of application (polygons) must be in one of the following permitted formats:
GeoJSON
WKT
WKB as hex
"shape": "01030000000100000005000000000000000000000000000000000000000000000000000000000000000000F03F000000000000F03F000000000000F03F000000000000F03F000000000000000000000000000000000000000000000000"
Regardless of the format, the spatial information must be in the WGS84 coordinate system (the default used by all GPS units).
For point spatial information, the latitude and longitude coordinates may be provided directly:
Basic Response Structure
It is strongly recommended that the URL parameter output be set to json or not be provided as JSON provides structure not found in the other output formats. This section assumes that the response is a JSON object.
The response object has the following structure.
If there are no errors or warnings, the respective key will not be present in the message object. If there are no errors AND warnings, the message object will not exist in the response.
If the data object is not present, an error occurred in the export process.
Example
Example
{
"message": {
"Warning": [
"No data matched the provided filter criteria. By relaxing the filter criteria, some data may match."
]
}
}
Specific Request/Response Structure
Application Source
Request
{
"type": "source",
"filter": {
"code": ([
"SOURCE_CODE",
...
"SOURCE_CODE"
] |
"SOURCE_CODE",
),
"local": ([
"LOCAL_ID",
...
"LOCAL_ID"
] |
"LOCAL_ID"
),
"shape": "SHAPE",
"habitat": ([
"HABITAT",
...
"HABITAT"
] |
"HABITAT"
)
}
}
Pesticide Application
Request
{
"type": "application",
"filter": {
"local": ([
"LOCAL_ID",
...
"LOCAL_ID"
] |
"LOCAL_ID"
),
"starttime": {
"from": ({
"value": "FROM_STARTTIME",
"format": "(Y-M-D)"
} |
"FROM_STARTTIME"
)
"to": ({
"value": "TO_STARTTIME",
"format": "(Y-M-D)"
} |
"TO_STARTTIME"
)
},
"endtime": {
"from": ({
"value": "FROM_ENDTIME",
"format": "(Y-M-D)"
} |
"FROM_ENDTIME"
)
"to": ({
"value": "TO_ENDTIME",
"format": "(Y-M-D)"
} |
"TO_ENDTIME"
)
},
"technician": ([
"TECHNICIAN_NAME" | "TECHNICIAN_CERT_NAME",
...
"TECHNICIAN_NAME" | "TECHNICIAN_CERT_NAME"
] |
"TECHNICIAN_NAME"
|
"TECHNICIAN_CERT_NUM"
),
"shape": ([
"SHAPE",
...
"SHAPE"
] |
"SHAPE"
),
"habitat": ([
"HABITAT",
...
"HABITAT"
] |
"HABITAT"
),
"purpose": ([
"PURPOSE",
...
"PURPOSE"
] |
"PURPOSE"
)
"mix": ({
"code": ([
"MIX_CODE",
...
"MIX_CODE"
] |
"MIX_CODE"
),
"local": ([
"LOCAL_ID",
...
"LOCAL_ID"
] |
"LOCAL_ID"
)
} | [
"MIX_CODE",
...
"MIX_CODE"
] | [
"LOCAL_ID",
...
"LOCAL_ID"
] |
"MIX_CODE"
|
"LOCAL_ID"
),
"product": ([
"CDPR_REGISTRATION_NUM",
...
"CDPR_REGISTRATION_NUM"
] |
"CDPR_REGISTRATION_NUM"
),
"diluent": ([
"DILUENT_NAME",
...
"DILUENT_NAME"
] |
"DILUENT_NAME"
),
"delivery": ([
"DELIVERY_METHOD",
...
"DELIVERY_METHOD"
] |
"DELIVERY_METHOD"
)
}
}
Pesticide Mix
Request
{
"type": "mix",
"filter": {
"code": ([
"MIX_CODE",
...
"MIX_CODE"
] |
"MIX_CODE",
),
"local": ([
"LOCAL_ID",
...
"LOCAL_ID"
] |
"LOCAL_ID"
),
"product": ([
"CDPR_REGISTRATION_NUM",
...
"CDPR_REGISTRATION_NUM"
] |
"CDPR_REGISTRATION_NUM"
),
"diluent": ([
"DILUENT_NAME",
...
"DILUENT_NAME"
] |
"DILUENT_NAME"
),
}
}
Application Equipment
Request
{
"type": "equipment",
"filter": {
"code": ([
"EQUIPMENT_CODE",
...
"EQUIPMENT_CODE"
] | "EQUIPMENT_CODE",
),
"local": ([
"LOCAL_ID",
...
"LOCAL_ID"
] | "LOCAL_ID",
),
"delivery": ([
"DELIVERY_METHOD",
...
"DELIVERY_METHOD"
] |
"DELIVERY_METHOD"
),
}
}
Product
Request
{
"type": "product",
"filter": {
"dpr_registration_num": ([
"DPR_REGISTRATION_NUM",
...
"DPR_REGISTRATION_NUM"
] | "DPR_REGISTRATION_NUM",
),
"product_name": ([
"PRODUCT_NAME",
...
"PRODUCT_NAME"
] | "PRODUCT_NAME",
),
}
}
Response
{
"data": {
"DPR_REGISTRATION_NUM" : {
"product_name": "PRODUCT_NAME",
"product_status_code": "PRODUCT_STATUS_CODE",
"product_status_info": "PRODUCT_STATUS_INFO",
"aerial_ground_code": "AERIAL_GROUND_CODE",
"aerial_ground_info": "AERIAL_GROUND_INFO",
"formulation_dry_or_liquid": "FORMULATION_DRY_OR_LIQUID",
"formulation_info": "FORMULATION_INFO",
"registration_date": "REGISTRATION_DATE",
"inactivation_date": "INACTIVATION_DATE",
"general_pesticide_code": "GENERAL_PESTICIDE_CODE",
"general_pesticide_info": "GENERAL_PESTICIDE_INFO",
...
}
}