Occurrence Set Service Description The Lifemapper Occurrence Set Service allows users to get an occurrence set, list sets that fit desired criteria, or post a new occurrence set.
Occurrence sets are groups of occurrence points. They are generally all from the same species, but do not have to be. They should, however, be related enough that creating a model would make sense. For example, if you wanted to create a model of prey for a certain species, you could create an occurrence set of all of the points where any of those species occurred. Getting a List of Occurrence Sets If you call http://lifemapper.org/services/lm2/occurrences/xml with an HTTP GET request, a list of available occurrence sets will be returned.
The items returned in this list can be filtered using a number of url parameters. A full list of the available filter parameters can be found in the Lifemapper web services WADL document. You can get an idea of how the parameters work by visiting the listing service with a web browser. A form will be presented at the top of the page that will allow you to filter the results as well as display the filters used to generate that page of results.
One use of this service is to find occurrence sets that have enough points to be modeled. The Lifemapper pipeline will pick occurrence sets with fifty or more points and then model them, but you are free to set your own threshold for the models you request. The filter needed for this operation is named "minimumNumberOfPoints" and for this example we will set it to 500. The resulting url is:
http://lifemapper.org/services/lm2/occurrences/xml?minimumNumberOfPoints=500 .
The list of occurrence sets is available in a variety of formats. These formats do not contain the point data from the occurrence sets, just metadata about them.
Formats available: Getting an Individual Occurrence Set You will need the occurrence set id number to return an individual occurrence set. You can browse the list of occurrence sets to find the occurrence set you would like, and just click the link. Alternatively, you can browse the occurrence sets associated with an experiment you may have submitted using that service.
Get an Individual Occurrence Set Method explains in more detail how this service works.
Formats available: Posting an Occurrence Set When you submit an experiment through the experiment submission page. You actually have the opportunity to upload points as well. Just click the "Upload Points!" button on the first page and it will bring up a dialog to help you.
Additionally, you can post an occurrence set directly. We currently accept points in CSV, Shapefile, and XML formats. See the links below:
Posting an occurrence set from Comma-Separated Values
Detailed documentation about this service is available on the Lifemapper web services WADL document.
To post an occurrence set from CSV points, you will need to send an HTTP POST request to the proper URL and include the CSV points as the message body of the request.
Lets first start with determining the correct URL that the post request should be sent to. You will need to know which Lifemapper user should own the new occurrence set and the display name you would like to use. For this example, we will use the public anonymous user, "anon". If you have a Lifemapper user and are logged in, you can use your user id instead and only you will be able to see your occurrence set. We will also use "example" for the display name for this occurrence set. The resulting url is:
http://lifemapper.org/services/anon/occurrences/xml?pointsType=csv&displayName=example
Please note that the "pointsType" url parameter indicates that the incoming data is in CSV format. This is required so that it can be processed.
Now on to the message body. This is where the actual data about the points will be uploaded. We strongly recommend that you include a header row in your CSV. If it is not present, then the service will assume that you are only uploading the minimum required data (local id, longitude, latitude) and that it is in that order. For this example, we will use more complete data. You can also see a sample occurrence set in CSV format by following this link.
LocalId,Longitude,Latitude,CanonicalName,CatalogNum,CollectionCode,CollectionDate,Collector,Guid,InstitutionCode,ModTime,ProviderName,ResourceName 1,-86.34,44.00,"Example name","sCat1-1","My Collection","2009-07-07","John Doe","http://example.com/myCollection/guids/1","My Institution","2009-07-07 13:43:34","My Provider","My Resource" 2,-87.42,43.89,"Example name","sCat1-2","My Collection","2009-07-07","John Doe","http://example.com/myCollection/guids/2","My Institution","2009-07-07 13:44:51","My Provider","My Resource" 3,-86.51,43.98,"Example name","sCat1-3","My Collection","2009-07-07","John Doe","http://example.com/myCollection/guids/3","My Institution","2009-07-07 13:46:21","My Provider","My Resource"
Now after the above message is posted the response from the service will be something like:
<?xml version="1.0" encoding="utf-8"?> <?xml-stylesheet type="text/xsl" href="/css/services.xsl"?> <lm:response xmlns:lm="http://lifemapper.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://lifemapper.org /schemas/serviceResponse.xsd"> <lm:title>Successfully posted occurrence set(s)</lm:title> <lm:user>lm2</lm:user> <lm:urls> <lm:url> http://lifemapper.org/services/anon/occurrences/3740257 </lm:url> </lm:urls> </lm:response> The HTTP response code should be 201. If it is 400 check your request. If it is anything else, contact us at: lifemapper [at] ku [dot] edu for help.
When you read the response, note that the element in: lm:response/lm:urls/lm:url will contain a url pointing to your new occurrence set. Keep note of the occurrence set id which is the number listed at the end of the url. In this case, the occurrence set id is 3740257.
Posting an occurrence set from a Shapefile
Detailed documentation about this service is available on the Lifemapper web services WADL document.
To post an occurrence set from a Shapefile, you will need to send an HTTP POST request to the proper URL and include the zipped shapefile as the message body of the request.
Lets first start with determining the correct URL that the post request should be sent to. You will need to know which Lifemapper user should own the new occurrence set and the display name you would like to use. For this example, we will use the public anonymous user, "anon". If you have a Lifemapper user and are logged in, you can use your user id instead and only you will be able to see your occurrence set. We will also use "example" for the display name for this occurrence set. The resulting url is:
http://lifemapper.org/services/anon/occurrences/xml?pointsType=shapefile&displayName=example
Please note that the "pointsType" url parameter indicates data is coming in as a Shapefile. This is required so that it can be processed.
The message body should contain all of the required files (.shp, .shx, .dbf) zipped into one.
Now after the above message is posted the response from the service will be something like:
<?xml version="1.0" encoding="utf-8"?> <?xml-stylesheet type="text/xsl" href="/css/services.xsl"?> <lm:response xmlns:lm="http://lifemapper.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://lifemapper.org /schemas/serviceResponse.xsd"> <lm:title>Successfully posted occurrence set(s)</lm:title> <lm:user>lm2</lm:user> <lm:urls> <lm:url> http://lifemapper.org/services/anon/occurrences/3740259 </lm:url> </lm:urls> </lm:response> The HTTP response code should be 201. If it is 400 check your request. If it is anything else, contact us at: lifemapper [at] ku [dot] edu for help.
When you read the response, note that the element in: lm:response/lm:urls/lm:url will contain a url pointing to your new occurrence set. Keep note of the occurrence set id which is the number listed at the end of the url. In this case, the occurrence set id is 3740259.
Posting an occurrence set from an XML document
Detailed documentation about this service is available on the Lifemapper web services WADL document.
To post an occurrence set from XML points, you will need to send an HTTP POST request to the proper URL and include the XML points as the message body of the request.
Lets first start with determining the correct URL that the post request should be sent to. You will need to know which Lifemapper user should own the new occurrence set and the display name you would like to use. For this example, we will use the public anonymous user, "anon". If you have a Lifemapper user and are logged in, you can use your user id instead and only you will be able to see your occurrence set. The resulting url is:
http://lifemapper.org/services/anon/occurrences/xml?pointsType=xml
Please note that the "pointsType" url parameter indicates that the incoming data is in XML format. This is required so that it can be processed.
Now on to the message body. This is where the actual data about the points will be uploaded. Your document should follow the schema at: http://lifemapper.org/schemas/serviceRequest.xsd. For the example, we will use the sample occurrences found at: http://lifemapper.org/samples/sampleOccurrencesRequest.xml.
<?xml version="1.0" encoding="utf-8"?> <lm:request xmlns:lm="http://lifemapper.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://lifemapper.org /schemas/serviceRequest.xsd"> <lm:occurrenceSet> <lm:displayName> Sample Display Name </lm:displayName> <lm:points> <lm:point localId="1" longitude="-45.0" latitude="30.0" canonicalName="Sample Name" catalogNum="S-1" collectionCode="Sample Collection" collectionDate="2009-04-01" collector="Sample Collector" guid="http://example.com/guid/s-1" institutionCode="Sample Institution" modTime="2009-05-01" providerName="Sample Provider" resourceName="Sample Resource" /> <lm:point localId="2" longitude="-43.4" latitude="31.6" canonicalName="Sample Name" catalogNum="S-2" collectionCode="Sample Collection" collectionDate="2009-04-01" collector="Sample Collector" guid="http://example.com/guid/s-2" institutionCode="Sample Institution" modTime="2009-05-01" providerName="Sample Provider" resourceName="Sample Resource" /> <lm:point localId="3" longitude="-43.0" latitude="32.7" canonicalName="Sample Name" catalogNum="S-3" collectionCode="Sample Collection" collectionDate="2009-04-01" collector="Sample Collector" guid="http://example.com/guid/s-3" institutionCode="Sample Institution" modTime="2009-05-01" providerName="Sample Provider" resourceName="Sample Resource" /> <lm:point localId="4" longitude="-42.9" latitude="31.1" canonicalName="Sample Name" catalogNum="S-4" collectionCode="Sample Collection" collectionDate="2009-04-01" collector="Sample Collector" guid="http://example.com/guid/s-4" institutionCode="Sample Institution" modTime="2009-05-01" providerName="Sample Provider" resourceName="Sample Resource" /> <lm:point localId="5" longitude="-43.4" latitude="33.4" canonicalName="Sample Name" catalogNum="S-5" collectionCode="Sample Collection" collectionDate="2009-04-01" collector="Sample Collector" guid="http://example.com/guid/s-5" institutionCode="Sample Institution" modTime="2009-05-01" providerName="Sample Provider" resourceName="Sample Resource" /> <lm:point localId="6" longitude="-45.3" latitude="32.3" canonicalName="Sample Name" catalogNum="S-6" collectionCode="Sample Collection" collectionDate="2009-04-01" collector="Sample Collector" guid="http://example.com/guid/s-6" institutionCode="Sample Institution" modTime="2009-05-01" providerName="Sample Provider" resourceName="Sample Resource" /> <lm:point localId="7" longitude="-43.3" latitude="30.2" canonicalName="Sample Name" catalogNum="S-7" collectionCode="Sample Collection" collectionDate="2009-04-01" collector="Sample Collector" guid="http://example.com/guid/s-7" institutionCode="Sample Institution" modTime="2009-05-01" providerName="Sample Provider" resourceName="Sample Resource" /> <lm:point localId="8" longitude="-43.1" latitude="30.4" canonicalName="Sample Name" catalogNum="S-8" collectionCode="Sample Collection" collectionDate="2009-04-01" collector="Sample Collector" guid="http://example.com/guid/s-8" institutionCode="Sample Institution" modTime="2009-05-01" providerName="Sample Provider" resourceName="Sample Resource" /> <lm:point localId="9" longitude="-41.8" latitude="33.0" canonicalName="Sample Name" catalogNum="S-9" collectionCode="Sample Collection" collectionDate="2009-04-01" collector="Sample Collector" guid="http://example.com/guid/s-9" institutionCode="Sample Institution" modTime="2009-05-01" providerName="Sample Provider" resourceName="Sample Resource" /> <lm:point localId="10" longitude="-40.6" latitude="32.7" canonicalName="Sample Name" catalogNum="S-10" collectionCode="Sample Collection" collectionDate="2009-04-01" collector="Sample Collector" guid="http://example.com/guid/s-10" institutionCode="Sample Institution" modTime="2009-05-01" providerName="Sample Provider" resourceName="Sample Resource" /> <lm:point localId="11" longitude="-42.3" latitude="31.9" canonicalName="Sample Name" catalogNum="S-11" collectionCode="Sample Collection" collectionDate="2009-04-01" collector="Sample Collector" guid="http://example.com/guid/s-11" institutionCode="Sample Institution" modTime="2009-05-01" providerName="Sample Provider" resourceName="Sample Resource" /> </lm:points> </lm:occurrenceSet> </lm:request>
Now after the above message is posted the response from the service will be something like:
<?xml version="1.0" encoding="utf-8"?> <?xml-stylesheet type="text/xsl" href="/css/services.xsl"?> <lm:response xmlns:lm="http://lifemapper.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://lifemapper.org /schemas/serviceResponse.xsd"> <lm:title>Successfully posted occurrence set(s)</lm:title> <lm:user>lm2</lm:user> <lm:urls> <lm:url> http://lifemapper.org/services/anon/occurrences/3740258 </lm:url> </lm:urls> </lm:response> The HTTP response code should be 201. If it is 400 check your request. If it is anything else, contact us at: lifemapper [at] ku [dot] edu for help.
When you read the response, note that the element in: lm:response/lm:urls/lm:url will contain a url pointing to your new occurrence set. Keep note of the occurrence set id which is the number listed at the end of the url. In this case, the occurrence set id is 3740258.