username={yourusername} password={yourpassword} content={sampleinformation} 

• You can upload multiple samples by adding the <sample></sample> block nested in the <samples></samples> tag. The sample xml schema is here. You can find the XML sample template at this link.

Response body

HTTP status codes:

200 Sample registered successfully. The response text is like the following.

<results> <sample> <status>Sample [Lulin Upload Status Sample test] was saved successfully with IGSN [LLS00009I].</status> <name>Lulin Upload Status Sample test</name> <igsn>LLS00009I</igsn> </sample> </results>

400 Bad Request - Request body either has syntax errors or xml content has errors. Error messages will look like the following.

    XML Syntax error:

<results> <valid code="InvalidXML">no</valid> <error>Element '{http://app.geosamples.org}publish_date':[facet 'pattern'] The value '2016-03-0' is not accepted by the patter '([0-9]{4}-[0-9]{2})(.........)'</error> .......... </results>

XML content error:

<results><sample name="your sample name"> <valid code="InvalidSample">no</valid><status>Not Saved</status> <error>The User Code ABC in your IGSN ABC123456 does not belong to you.</error> ...... </sample> </results>

401 Unauthorized - A login failure will return text as following.

<results> <valid code="InvalidAuth">no</valid> <error>Invalid login, username not known or password not matched</error> </results>

2. Validate user credentials and get user code

• The web service is at: https://app.geosamples.org/webservices/credentials_service_v2.php.
• It will check the user's credentials. If valid, it will return user code(s). If not valid, it will return error messages. It only accepts POST requests from the client program. GET, PUT and DELETE are not supported.
• Notes:
  • (Deprecated) The older version v1 end point is https://app.geosamples.org/webservices/credentials_service.php
  • Starting from version 2, the user is allowed to access other user's user code with different permissions. In v1 the user has to create a user code for his/her samples .

  Before you use this web service, you need to do the following two steps:

• Create a free GeoPass account. Follow this link.
•  Log in to the SESAR system to create your namespace or user code. If you would like to use other user's user code, you can login to the system and make a request. Follow this link .

POST API

URI: https://app.geosamples.org/webservices/credentials_service_v2.php

Request headers

• Requires HTTP Basic Authentication header. http://en.wikipedia.org/wiki/Basic_access_authentication
• Accept: text/xml, application/xml

Request body

username={yourusername} password={yourpassword}

Response body

HTTP status codes:

200 Successful. User name and password are valid. It will return user code(s) as following.

<results> <valid>yes</valid> <user_codes> <user_code>MOB</user_code> </user_codes> </results> 

401 Unauthorized - A login failure will return text as following.

<results> <valid>no</valid> <error>Invalid login, username not known or password not matched</error> </results>

Usage Examples:

Example 1: command line example curl --data " username=your_user_name& password=your_password"  https://app.geosamples.org/ webservices/credentials_service_v2.php

Example 2. php script

  <?php  function curl_http_post_request($requestdata) {     $ch = curl_init();   curl_setopt($ch,CURLOPT_SSL_VERIFYPEER,false); curl_setopt($ch, CURLOPT_URL, $requestdata["url"]);   curl_setopt($ch,CURLOPT_POST,true); curl_setopt($ch,CURLOPT_POSTFIELDS, $requestdata["data"]);      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);  $result["content"]= curl_exec($ch);  $result["errno"]= curl_errno($ch); $result["errmsg"] = curl_error($ch) ;  $result["header"] = curl_getinfo($ch);  curl_close($ch);      return $result; }    $baseurl=" https://app.geosamples.org/ webservices/credentials_service_v2.php";  $username="your_user_name"; $password="your_password";  $requestinfo["url"]=$baseurl;  requestinfo["data"]=array ("username"=>$username, "password"=>$password);   $result=curl_http_post_request($requestinfo);   echo $result["content"].PHP_EOL;  echo $result["header"]["http_code"].PHP_EOL;  echo $result["errno"].PHP_EOL;  echo $result["errmsg"].PHP_EOL;  ?>  

3. IGSN list for specific user code

• The end point is https://app.geosamples.org/samples/user_code.
  • E.G. https://app.geosamples.org/samples/user_code/IEUHM
    • User code examples: IEUHM or IELCZ, ODP, NHB or HRV
• The service will retrieve all IGSNs for a specific user code. It only accepts GET requests from client programs. It does not require login and password and supports pagination. If 'hide_private' flag is set to 1, it will not return IGSNs whose sample metadata are not public accessible.

GET API

Request headers

• Accept: application/xml, application/json, text/xml, text/json

Request body

limit={limit} maximum IGSN number for each page. If it is not specified, it will default to 100. page_no={page_no} page number. If it is not specified, it will default to 1. hide_private={1 or 0 or none} default to 0 If 1, it will not return IGSNs whose sample metadata are not public accessible.

Response body

HTTP status codes:

• 400 Bad Request - User Code is not valid.
• 404 Not Found - No IGSNs associated with the given user code.
• 200 successful. It will return a list of IGSN(s) as following.

Output format when request is successful ( status code = 200 ) XML format:

<samples>

<sample> <igsn>LLS00000L</igsn> <url>https://app.geosamples.org/webservices/display.php?igsn=LLS00000L</url> </sample><sample> <igsn>LLS00000M</igsn> <url>https://app.geosamples.org/webservices/display.php?igsn=LLS00000M</url> </sample><sample> <igsn>LLS00000N</igsn> <url>https://app.geosamples.org/webservices/display.php?igsn=LLS00000N</url> </sample>...... 

<total_counts>320</total_counts><previous_list>https://app.geosamples.org/samples/user_code/LLS?limit=20&page_no=1</previous_list> <next_list>https://app.geosamples.org/samples/user_code/LLS?limit=20&page_no=3</next_list> </samples>   JSON format:   

{ "igsn_list": [ "MOB000001", "MOB000002", "MOB000003", "MOB000004", ...... ], "total_counts":450, "previous_list": [ "http: //app.geosamples.org/samples/user_code/MOB?limit=100&page_no=1" ], "next_list": [ "http: //app.geosamples.org/samples/user_code/MOB?limit=100&page_no=3" ] }

Example:

curl -X GET -H "accept: application/xml" "https://app.geosamples.org/samples/user_code/ARF?limit=20&page_no=2&hide_private=1"

4. IGSN list for a geospatial polygon

• The end point is https://app.geosamples.org/samples/polygon
• Usage: https://app.geosamples.org/samples/polygon/[lon1 lat1, lon2 lat2, lon3 lat3, lon4 lat4, lon1,lat1].
  • [lon1 lat1, lon2 lat2, lon3 lat3, lon4 lat4, lon1 lat1] are points of a concave polygon. Please note that the last point is the same as the first point.
• The service will retrieve all IGSNs whose geo-coordinates are located within the user defined polygon. It only accepts GET requests from the client program. It does not require login and password and supports pagination. If 'hide_private' flag is set to 1, it will not return IGSNs whose sample metadata are not public accessible. It supports spatial reference systems transformation.

GET API

Request headers

• Accept: application/xml, application/json, text/xml, text/json

Request body

lon1 lat1, lon2 lat2, lon3 lat3, lon4 lat4, lon1 lat1 = longitudes, latitudes for a polygon limit={limit} maximum IGSN number for each page. If it is not specified, it will default to 100. page_no={page_no} page number. If it is not specified, it will default to 1. hide_private={1 or 0 or none} default to 0

If 1, it will not return IGSNs whose sample metadata are not public accessible.

srs={SRID number} Spatial Reference System Identifier (SRID). If it is not specified, it will default to EPSG:4326.

Response body

HTTP status codes:

• 400 Bad Request - User specified polygon is not valid.
• 404 Not Found - No IGSNs associated with the given polygon
• 200 Successful. It will return a list of IGSN(s) as following.

Output format when request is successful ( status code = 200 ) XML format: <samples><sample> <igsn>LCZ7700AN</igsn> <url>https://app.geosamples.org/webservices/display.php?igsn=LCZ7700AN</url> </sample> <sample> <igsn>LCZ7700AM</igsn> <url>https://app.geosamples.org/webservices/display.php?igsn=LCZ7700AM</url> </sample> <sample> <igsn>LCZ7700AL</igsn> <url>https://app.geosamples.org/webservices/display.php?igsn=LCZ7700AL</url> </sample> <sample> <igsn>LCZ7700AK</igsn> <url>https://app.geosamples.org/webservices/display.php?igsn=LCZ7700AK</url> </sample> <total_counts>1489</total_counts> <previous_list>https://app.geosamples.org/samples/polygon/-67.4156 18.6972,-67.4968 17.6568,-65.4526 17.6865,-65.5252 18.5649,-67.4156 18.6972?limit=4&amp;page_no=1&amp;hide_private=1</previous_list> <next_list>https://app.geosamples.org/samples/polygon/-67.4156 18.6972,-67.4968 17.6568,-65.4526 17.6865,-65.5252 18.5649,-67.4156 18.6972?limit=4&amp;page_no=3&amp;hide_private=1</next_list> </samples> JSON format:   

{ "igsn_list": [ "LCZ7700AN", "LCZ7700AM", "LCZ7700AL", "LCZ7700AK" ], "total_counts": 1489, "previous_list": "https://app.geosamples.org/samples/polygon/-67.4156 18.6972,-67.4968 17.6568,-65.4526 17.6865,-65.5252 18.5649,-67.4156 18.6972?limit=4&page_no=1&hide_private=1", "next_list": "https://app.geosamples.org/samples/polygon/-67.4156 18.6972,-67.4968 17.6568,-65.4526 17.6865,-65.5252 18.5649,-67.4156 18.6972?limit=4&page_no=3&hide_private=1" }

 Please note: Total count of IGSNs is tagged as "total_counts" in the returned content. If limits, page numbers, etc. are specified, the returned content will have <previous_list> and <next_list> tags when there are more than one page of IGSNs.

Example:

curl -X GET -H "accept: application/xml" "https://app.geosamples.org/samples/ polygon/-67.4156%2018.6972,-67.4968%2017.6568, -65.4526%2017.6865,-65.5252%2018.5649, -67.4156%2018.6972& hide_private=1&limit=4&page_no=2"

curl -X GET -H " accept: application/json" "https://app.geosamples.org/samples/ polygon/-67.4156%2018.6972,-67.4968%2017.6568, -65.4526%2017.6865,-65.5252%2018.5649, -67.4156%2018.6972& hide_private=1&limit=4&page_no=2"

NEW curl -X GET -H " accept: application/json" "https://app.geosamples.org/samples/ polygon/-43096291.5430165%20223829530.742031, -53338557.3468762%20277024863.02079, 87260142.0817049%20268278668.61794,70504128. 9133862%20216762812.731158,-43096291.5430165%20223829530.742031 &srs=3031&hide_private=1& limit=4&page_no=2"

5. IGSN list for a specific field program

•  The end point is https://app.geosamples.org/samples/field_program
  • Usage: https://app.geosamples.org/samples/field_program/[field program name].
•  The service will retrieve all IGSNs for a user defined field program. It only accepts GET requests from client programs. It does not require login and password and supports pagination. If 'hide_private' flag is set to 1, it will not return IGSNs whose sample metadata are not public accessible.

GET API

Request headers

• Accept: application/xml, application/json, text/xml, text/json

Request body

field program name = exact name of the field program (case sensitive) limit={limit} maximum number of IGSNs for each page. If it is not specified, it will default to 100. page_no={page_no} page number. If it is not specified, it will default to 1. hide_private={1 or 0 or none} default to 0

If 1, it will not return IGSNs whose sample metadata are not public accessible.

Response body

HTTP status codes:

• 400 Bad Request - Field program name is not valid.
• 404 Not Found - No IGSNs associated with the given field program name.
• 200 successful. It will return user IGSN(s) as follows.

Output format when request is successful ( status code = 200 ) XML format: <samples><sample> <igsn>SSH0002V6</igsn> <url>https://app.geosamples.org/webservices/display.php?igsn=SSH0002V6</url> </sample> <sample> <igsn>SSH0002V5</igsn> <url>https://app.geosamples.org/webservices/display.php?igsn=SSH0002V5</url> </sample> <sample> <igsn>SSH0002V4</igsn> <url>https://app.geosamples.org/webservices/display.php?igsn=SSH0002V4</url> </sample> <sample> <igsn>SSH0002V3</igsn> <url>https://app.geosamples.org/webservices/display.php?igsn=SSH0002V3</url> </sample> <total_counts>4339</total_counts> <previous_list>https://app.geosamples.org/samples/field_program/Susquehanna Shale Hills Critical Zone Observatory (CZO)?limit=4&amp;page_no=99&amp;hide_private=0</previous_list> <next_list>https://app.geosamples.org/samples/field_program/Susquehanna Shale Hills Critical Zone Observatory (CZO)?limit=4&amp;page_no=101&amp;hide_private=0</next_list> </samples> JSON format:   

{ "igsn_list": [ "SSH0002V6", "SSH0002V5", "SSH0002V4", "SSH0002V3" ], "total_counts": 4339, "previous_list": "https://app.geosamples.org/samples/field_program/Susquehanna Shale Hills Critical Zone Observatory (CZO)?limit=4&page_no=99&hide_private=0", "next_list": "https://app.geosamples.org/samples/field_program/Susquehanna Shale Hills Critical Zone Observatory (CZO)?limit=4&page_no=101&hide_private=0" }

 Please note: Total count of IGSNs is tagged as "total_counts" in the returned content. If limits, page numbers, etc. are specified, the returned content will have <previous_list> and <next_list> tags when there are more than one page of IGSNs.

Example:

curl -X GET -H "accept: application/xml" "https://app.geosamples.org/samples/field_program /Susquehanna%20Shale%20Hills%20Critical %20Zone%20Observatory%20(CZO)& limit=4&page_no=100";

6. Sample Profile for specific IGSN

• The end point is https://app.geosamples.org/sample/igsn or The old end point is https://app.geosamples.org/webservices/display.php
  • Usage: https://app.geosamples.org/sample/igsn/XXXXXXXXX
  •               https://app.geosamples.org/webservices/display.php?igsn=XXXXXXXXX
    • XXXXXXXX is the IGSN of a sample. e.g., GEE0000O4, ODP000002
• The service will retrieve most metadata of the sample. It only accepts GET requests from the client program. User name and password are not required. If they are provided, none public accessible sample metadata will be returned also.

GET API

Request headers

• Accept: text/xml, application/xml, application/json, text/json

Request body

igsn={igsn} username={yourusername} (optional) password={yourpassword} (optional)

Response body

HTTP status codes:

• 400 Bad Request -  IGSN is not valid.
• 403 Forbidden - IGSN is either deactived or has no public metadata.
• 404 Not Found - IGSN not found.
• 200 Successful. It will return metadata related to the IGSN.

Output format when request is successful ( status code = 200 )

• XML format:

  (NEW) The returned xml file uses the following xml schema. https://app.geosamples.org/4.0/downloadSample.xsd

Notes:To be backward compatible, the old end point (https://app.geosamples.org/webservices/display.php?igsn=XXXXXXXXX) will return the old XML format if the user executes from the browser or sends ACCEPT header with 'text/html'. The old format is as follows. <results> <user_code>XXX</user_code><igsn>XXXXXXXXX</igsn><name>myname</name> .... </results> The old end point was REST-Type so it did not follow HTTP protocol standards. If your client program used any HTTP standards such as relying on HTTP status code, you need to adjust them according to the current documentation.

• JSON format:   

         { "sample": { "qrcode_img_src": "app.geosamples.org/barcode/image.php?igsn=ODP000002&sample_id=Core 1-1*-1M", "user_code": "ODP", "igsn": "ODP000002", "name": "Core 1-1*-1M", "sample_type": "Core", "sample_subtype": "Thin Section", "parent_igsn": "ODP000001", "collection_method": "Coring", "collection_method_description": "M: This represents material that could not be labeled with a standard core type.  This category includes limited numbers of cores which are recovered using experimental drilling methods which, once they are established, are assigned their own core type.", "latitude": "25.8583", "longitude": "-92.1833", "elevation": "-2827", "cruise_field_prgrm": "DSDP Leg 1", "platform_type": "Ship", "platform_name": "Glomar Challenger", "collector": "Curator", "collector_detail": "Texas A&M University, Integrated Ocean Drilling Program, College Station, TX, 77845, USA", "current_archive": "Texas A&M University, Integrated Ocean Drilling Program, College Station, TX, 77845, USA", "current_archive_contact": "Curator", "original_archive": "Texas A&M University, Integrated Ocean Drilling Program, College Station, TX, 77845, USA", "original_archive_contact": "Texas A&M University, Integrated Ocean Drilling Program, College Station, TX, 77845, USA", "parents": { "samples": { "sample": { "igsn": "ODP000001", "name": "Hole 1-1*" } } }, "siblings": { "samples": { "sample": [ { "igsn": "ODP000003", "name": "Core 1-1*-1R" }, { "igsn": "ODP000004", "name": "Core 1-1*-2R" }, { "igsn": "ODP000005", "name": "Core 1-1*-3R" }, { "igsn": "ODP000006", "name": "Core 1-1*-40" }, { "igsn": "ODP000007", "name": "Core 1-1*-5R" }, { "igsn": "ODP000008", "name": "Core 1-1*-6R" }, { "igsn": "ODP000009", "name": "Core 1-1*-7R" }, { "igsn": "ODP000010", "name": "Core 1-1*-8R" }, { "igsn": "ODP000011", "name": "Core 1-1*-9R" } ] } }, "children": { "samples": { "sample": [ { "igsn": "ODP01133U", "name": "Section 1-1*-1M-1" }, { "igsn": "ODP01133Y", "name": "Section 1-1*-1M-2" }, { "igsn": "ODP011342", "name": "Section 1-1*-1M-3" }, { "igsn": "ODP011346", "name": "Section 1-1*-1M-4" }, { "igsn": "ODP01134A", "name": "Section 1-1*-1M-5" }, { "igsn": "ODP01134E", "name": "Section 1-1*-1M-6" }, { "igsn": "ODP01134I", "name": "Section 1-1*-1M-7" } ] } } } }

Example:

curl -X GET -H "accept: application/xml" "https://app.geosamples.org/webservices/display.php?igsn=ODP000002"

curl -X GET -H "accept: application/xml" "https://app.geosamples.org/sample/igsn/ODP000002" -L

curl -X GET -H "accept: application/xml" "https://app.geosamples.org/sample/igsn/ODP000002" -L -u yourusername

7. Update sample metadata

• The web service https://app.geosamples.org/webservices/update.php allows the client program to update registered sample(s) metadata profile(s).
• It only accepts POST requests from client programs. GET, PUT and DELETE are not supported.
• Notes:
  • The user should use the following test URI during client program testing, so production sample profiles are not accidentally edited.
    • https://sesardev.geosamples.org/webservices/update.php
  • New The user can replace an existing URL using 'old_url' element. See document in updateSample.xsd schema file. E.G. <external_urls><external_url><old_url>http://oneurl.tobereplaced.org </old_url><url>http://oneurl.new.org</url></external_url></external_urls>

POST API

URI: https://app.geosamples.org/webservices/update.php TEST URI: https://sesardev.geosamples.org/webservices/update.php

Request headers

• Requires HTTP Basic Authentication header. http://en.wikipedia.org/wiki/Basic_access_authentication
• Accept: text/xml, application/xml

Request body

username={yourusername} password={yourpassword} content={sampleinformation} 

where {sampleinformation} is the xml text.

• The text should use the following schema. https://app.geosamples.org/4.0/updateSample.xsd.

Example XML format for updating one sample profile:

<?xml version="1.0" encoding="UTF-8"?> <samples xmlns="http://app.geosamples.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://app.geosamples.org/4.0/updateSample.xsd "> <sample> <sample_type>Individual Sample</sample_type> <sample_subtype>Thin Section</sample_subtype> <name>TestSample123</name> <material>Rock</material> <igsn>ABC123456</igsn> <!-- Required. --> <!-- If no classification.xsd is specified, the older format for classification is still supported e.g., Igneous>Plutonic>Felsic --> <classification xmlns="http://app.geosamples.org" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://app.geosamples.org/classifications.xsd"> <Rock><Igneous> <Plutonic> <PlutonicType>Felsic</PlutonicType> </Plutonic> </Igneous></Rock> </classification> <description>arkose</description> <age_min>6.5</age_min> <age_max>13</age_max> <age_unit>years</age_unit> <collection_method>Grab</collection_method> <latitude>35.5134</latitude> <longitude>-117.3463</longitude> <elevation>781.4</elevation> <primary_location_name>Lava Mountains, Mojave Desert, California </primary_location_name> <country>United States</country> <province>California</province> <county>San Bernardino</county> <collector>J. E. Andrew</collector> <collection_start_date>2002-05-30T09:30:10Z </collection_start_date> <collection_date_precision>time</collection_date_precision> <original_archive>University of Kansas</original_archive> </sample> </samples>

• You can update multiple samples by adding the <sample></sample> block nested into the <samples></samples> tag.

Response body

HTTP status codes:

200 Sample registered successfully. The response text is as follows.

<results> <sample> <status>Sample [Lulin Update Status Sample test] was updated successfully with IGSN [LLS00009I].</status> <name>Lulin Update Status Sample test</name> <igsn>LLS00009I</igsn> </sample> </results>

400 Bad Request - Request body either has syntax errors or xml content has errors. Error messages will look like the following.

    XML Syntax error:

<results> <valid code="InvalidXML">no</valid> <error>Element '{http://app.geosamples.org}user_code':......</error> </results>

XML content error:

<results> <sample name="your sample name"> <valid code="InvalidSample">no</valid><status>Not Saved</status> <error>You do not have permission to edit the sample metadata.</error> ...... </sample> </results>

401 Unauthorized - A login failure will return text as follows.

<results> <valid code="InvalidAuth">no</valid> <error>Invalid login, username not known or password not matched</error> </results>