| |
- Wiki
- Installation
- Upgrading
- Media
- Readme
- Privacy
- Developers
|
|
This documentation describes how to use the SOAP webservices included in PGV version 4.0 and higher. This
documentation assumes that you are familiar with SOAP and web services.
The SOAP web services in PGV allow you to access the data remotely. In order to access the data through the
web service you need to have a SOAP client. The simplest way to create a SOAP client is through the WSDL file.
You can obtain the WSDL file for a PGV site by going to http://www.pgvsite.com/phpGedView/genservice.php?wsdl
Note: This documentation is a bit out of date. You should always follow what is documented in the WSDL.
You can implement your own compatible web service for your application by extending the class found in the
webservice/genealogyService.php file. For reference the PGV implementation can be found at webservice/PGVServiceLogic.class.php. These files are available here http://cvs.sourceforge.net/viewcvs.py/phpgedview/phpGedView/webservice/?only_with_tag=future.
API Functions in the Web Service
Note: All code snippets are using PHP with PEAR::SOAP 0.9.1b
● Authenticate -
Logs you into the service. Allows you to set the default gedcom and compression methods to use. All methods require the session id returned from this method with the exception of ServiceInfo.
Parameters
Name
|
Description
|
username
|
Username that has been created on the service you are trying to connect to. Leave blank to connect as a guest.
|
Password
|
Password for the provided username. Leave blank to connect as a guest.
|
gedcom_id
|
The gedcom id to use for all calls to the service. Defaults to the default gedcom set by the server. See also: ServiceInfo for a list of gedcoms on the server
|
Compression
|
Not implemented Choose the compression library to use. See also: ServiceInfo for a list of supported libraries
|
Returns - authResult
Name
|
Description
|
SID
|
Your session id. This must be provided when using any other methods of the service. Exception: ServiceInfo
|
Message
|
Server message to give details about the authentication attempt.
|
gedcom_id
|
The gedcom id that the server has chosen.
|
compressionMethod
|
Not implemented The compression method the server has chosen.
|
Example
| Request |
require_once('includes/SOAP.php');
$url = 'http://www.example.com/genservice.php?wsdl';);
$wsdl = newSOAP_WSDL($url);
$soap = $wsdl->getProxy();
$auth = $soap->Authenticate('test,'mypassword','gedcom_id.ged','zlib');
// guest login, no params
$auth = $soap->Authenticate('','','','');
|
| Response |
...
<ns4:AuthenticateResponse>
<result xsi:type="ns4:authResult">
<SID xsi:type="xsd:string">aa5ec508a1e054292cae0b62442a7874</SID>
<message xsi:type="xsd:string">Logged in as test</message>
<compressionMethod xsi:type="xsd:string">zlib</compressionMethod>
<gedcom_id xsi:type="xsd:string">gedcom_id.ged</gedcom_id>
</result>
</ns4:AuthenticateResponse>
...
|
● SerivceInfo -
Provides information about the server and what it supports. Note: Only method that does not require authentication.
Parameters - ServiceInfo does not take any parameters
Returns - ServiceInfo
Name
|
Description
|
compression
|
Comma delimited list of supported compression libraries (ie. none,zlib,zip)
|
apiVersion
|
Version of the API
|
server
|
The server's identification (ie. PHPGedView 3.4)
|
gedcomList
|
ArrayOfGedcomList(Complex Type)
|
title
|
Title of the gedcom
|
id
|
Gedcom id
|
Example
| Request |
require_once('includes/SOAP.php');
$url = 'http://www.example.com/genservice.php?wsdl';);
$wsdl = newSOAP_WSDL($url);
$soap = $wsdl->getProxy();
$service_info = $soap->ServiceInfo();
|
| Response |
...
<ns4:serviceInfoResponse>
<return xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="Struct[1]" SOAP-ENC:offset="[0]">
<item>
<compression xsi:type="xsd:string">none,zlib,zip</compression>
<apiVersion xsi:type="xsd:string">1.0a</apiVersion>
<server xsi:type="xsd:string">PHPGedView CVS 3.4</server>
<gedcomList xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="Struct[2]" SOAP-ENC:offset="[0]">
<item>
<title xsi:type="xsd:string">My testing gedcom file</title>
<ID xsi:type="xsd:string">testing.ged</ID>
</item>
<item>
<title xsi:type="xsd:string">Presidents</title>
<ID xsi:type="xsd:string">presidents.ged</ID>
</item>
</gedcomList>
</item>
</return>
</ns4:serviceInfoResponse>
...
|
Note: The following methods all require a session id acquired from Authenticate
● doSearch -
Performs a basic or advanced search on the gedcom specified in Authenticate.
Parameters
Name
|
Description
|
SID
|
Session id that was returned from Authenticate
|
query
|
Query string to search with (ie 'John')
Supports keyword searching in the following syntax:
field=value&field2=value2
Keywords: NAME, BIRTHDATE, DEATHDATE, BIRTHPLACE, DEATHPLACE, GENDER
|
Start
|
Index of results to start at. To retrieve results 50 - <maxResults> you set start at 50
|
maxResults
|
Maximum number of results to return
|
Returns - SearchResult
Name
|
Description
|
totalResults
|
Total number of results found.
|
Persons
|
ArrayOfPerson(Complex Type)
|
PID
|
Person ID
|
gedcomName
|
Person's name in gedcom syntax
|
birthDate
|
Date of birth
|
birthplace
|
Place of birth
|
deathPlace
|
Place of death
|
deathDate
|
Date of death
|
gender
|
Gender
|
gedcom
|
Returns an empty string. See getPersonByID to retrieve gedcom
|
Example
| Request |
require_once('includes/SOAP.php');
$url = 'http://www.example.com/genservice.php?wsdl';);
$wsdl = newSOAP_WSDL($url);
$soap = $wsdl->getProxy();
$auth = $soap->Authenticate('testuser','pass','presidents.ged','none');
$search = $soap->doSearch($result->SID, 'George', '0','100');
|
| Response |
...
<ns4:doSearchResponse>
<Results xsi:type="ns4:SearchResult">
<totalResults xsi:type="xsd:int">2</totalResults>
<persons xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="Struct[2]" SOAP-ENC:offset="[0]">
<item>
<PID xsi:type="xsd:string">I1</PID>
<gedcomName xsi:type="xsd:string">George /Washington/</gedcomName>
<birthDate xsi:type="xsd:string">11 FEB 1732</birthDate>
<birthPlace xsi:type="xsd:string">Pope's Creek,Westmoreland Co.,Virginia</birthPlace>
<deathDate xsi:nil="true"/>
<deathPlace xsi:type="xsd:string">Mount Vernon, Fairfax Co., Virginia</deathPlace>
<gender xsi:type="xsd:string">M</gender></item>
<item>
<PID xsi:type="xsd:string">I3</PID>
<gedcomName xsi:type="xsd:string">Augustine /Washington/</gedcomName>
<birthDate xsi:type="xsd:string">1693/1694</birthDate>
<birthPlace xsi:type="xsd:string">Wakefield,Westmoreland Co.,Virginia</birthPlace>
<deathDate xsi:type="xsd:string">12 APR 1743</deathDate>
<deathPlace xsi:type="xsd:string">Ferry Farm,King George Co.,Virginia</deathPlace>
<gender xsi:type="xsd:string">M</gender>
</item>
</persons>
</Results>
</ns4:doSearchResponse>
...
|
● getPersonByID -
Retrieves information about the person with the given PID.
Parameters
Name
|
Description
|
SID
|
Session id that was returned from Authenticate.
|
PID
|
ID of the person record to retrieve information for.
|
Returns - Person
Name
|
Description
|
Result
|
Person(Complex Type)
|
PID
|
Person ID
|
gedcomName
|
Person's name in gedcom syntax
|
birthDate
|
Date of birth
|
birthplace
|
Place of birth
|
deathPlace
|
Place of death
|
deathDate
|
Date of death
|
gender
|
Gender
|
gedcom
|
Retruns the gedcom for the person
|
Example
| Request |
require_once('includes/SOAP.php');
$url = 'http://www.example.com/genservice.php?wsdl';);
$wsdl = newSOAP_WSDL($url);
$soap = $wsdl->getProxy();
$auth = $soap->Authenticate('testuser','pass','presidents.ged','none');
$gpbid = $soap->getPersonByID($auth->SID,'I1');
|
| Response |
...
<ns4:getPersonByIDResponse>
<result xsi:type="ns4:Person">
<result>
<PID xsi:type="xsd:string">I1</PID>
<gedcomName xsi:type="xsd:string">George /Washington/</gedcomName>
<birthDate xsi:type="xsd:string">11 FEB 1732</birthDate>
<birthPlace xsi:type="xsd:string">Pope's Creek,Westmoreland Co.,Virginia</birthPlace>
<deathDate xsi:nil="true"/>
<deathPlace xsi:type="xsd:string">Mount Vernon, Fairfax Co., Virginia</deathPlace>
<gender xsi:type="xsd:string">M</gender>
<gedcom xsi:type="xsd:string">0 @I1@ INDI
1 NAME George /Washington/
2 GIVN George
2 SURN Washington
1 SEX M
1 BIRT
2 DATE 11 FEB 1732
2 PLAC Pope's Creek,Westmoreland Co.,Virginia
1 DEAT
2 PLAC Mount Vernon, Fairfax Co., Virginia
1 BURI
2 PLAC Mount Vernon, Fairfax Co., Virginia
...
</gedcom>
</result>
</result>
</ns4:getPersonByIDResponse>
...
|
● getGedcomRecord -
Retrieves the gedcom string of the specified record.
Parameters
Name
|
Description
|
SID
|
Session id that was returned from Authenticate.
|
RID
|
Record ID to retrieve
|
Returns - string
Name
|
Description
|
result
|
Gedcom of the returned record
|
Example
Request
|
require_once('includes/SOAP.php');
$url = 'http://www.example.com/genservice.php?wsdl';);
$wsdl = newSOAP_WSDL($url);
$soap = $wsdl->getProxy();
$auth = $soap->Authenticate('testuser','pass','presidents.ged','none');
$ggr = $soap->getGedcomRecord($auth->SID,'F1');
|
Response
|
...
<ns4:getGedcomRecordResponse>
<result xsi:type="xsd:string">
<result xsi:type="xsd:string">0 @F1@ FAM
1 HUSB @I1@
1 WIFE @I2@
1 MARR
2 DATE 7 JAN 1759
2 PLAC New Kent Co.,Virginia
2 SOUR @
3 DATA
4 TEXT My personal knowledge. Lynn Ellsworth
1 CHAN
2 DATE 09 May 2005
3 TIME 17:32:30
1 SOUR @SPGV1@
2 PAGE http://10.245.27.43/pgv/pgv/family.php?famid=F1
2 DATA
3 TEXT This Family was downloaded from:
4 CONT http://10.245.27.43/pgv/family.php?famid=F1
</result>
</result>
</ns4:getGedcomRecordResponse>
... |
● getAncestry -
Retrieves the ancestry of the PID provided.
Parameters
Name
|
Description
|
SID
|
Session id that was returned from Authenticate.
|
rootID
|
Person ID to start the ancestry
|
generations
|
Number of generations to get
|
returnGedcom
|
Whether or not to return the gedcom
|
Returns - ArrayOfPerson
Name
|
Description
|
result
|
ArrayOfPerson(Complex Type)
|
PID
|
Person ID
|
gedcomName
|
Person's name in gedcom syntax
|
birthDate
|
Date of birth
|
birthplace
|
Place of birth
|
deathPlace
|
Place of death
|
deathDate
|
Date of death
|
gender
|
Gender
|
gedcom
|
Returns the gedcom
|
Example
Request
|
require_once('includes/SOAP.php');
$url = 'http://www.example.com/genservice.php?wsdl';);
$wsdl = newSOAP_WSDL($url);
$soap = $wsdl->getProxy();
$auth = $soap->Authenticate('testuser','pass','presidents.ged','none');
$ga = $soap->getAncestry($auth->SID,'I1',2,true);
|
Response
|
...
<ns4:getAncestryResponse>
<results xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="ns4:Person[2]" SOAP-ENC:offset="[0]">
<item>
<PID xsi:type="xsd:string">I3</PID>
<gedcomName xsi:type="xsd:string">Augustine /Washington/</gedcomName>
<birthDate xsi:type="xsd:string">1693/1694</birthDate>
<birthPlace xsi:type="xsd:string">Wakefield,Westmoreland Co.,Virginia</birthPlace>
<deathDate xsi:type="xsd:string">12 APR 1743</deathDate>
<deathPlace xsi:type="xsd:string">Ferry Farm,King George Co.,Virginia</deathPlace>
<gender xsi:type="xsd:string">M</gender>
<gedcom xsi:type="xsd:string">0 @I3@ INDI
1 NAME Augustine /Washington/
2 GIVN Augustine
2 SURN Washington
1 SEX M
1 BIRT
2 DATE 1693/1694
...
</gedcom>
</item>
<item>
<PID xsi:type="xsd:string">I4</PID>
<gedcomName xsi:type="xsd:string">Mary /Ball/</gedcomName>
<birthDate xsi:type="xsd:string">1708/1709</birthDate>
<birthPlace xsi:type="xsd:string">Lancaster Co.,VA</birthPlace>
<deathDate xsi:type="xsd:string">25 AUG 1789</deathDate>
<deathPlace xsi:type="xsd:string">Fredericksburg,VA</deathPlace>
<gender xsi:type="xsd:string">F</gender>
<gedcom xsi:type="xsd:string">0 @I4@ INDI
1 NAME Mary /Ball/
2 GIVN Mary
2 SURN Ball
2 _MARNM Mary /Washington/
1 SEX F
1 BIRT
2 DATE 1708/1709
...
</gedcom>
</item>
</results>
</ns4:getAncestryResponse>
...
|
● getDescendants -
Retrieves the descendancy of the PID provided.
Parameters
Name
|
Description
|
SID
|
Session id that was returned from Authenticate.
|
rootID
|
Person ID to start the descendancy
|
generations
|
Number of generations to get
|
returnGedcom
|
Whether or not to return the gedcom
|
Returns - ArrayOfPerson
Name
|
Description
|
result
|
ArrayOfPerson(Complex Type)
|
PID
|
Person ID
|
gedcomName
|
Person's name in gedcom syntax
|
birthDate
|
Date of birth
|
birthplace
|
Place of birth
|
deathPlace
|
Place of death
|
deathDate
|
Date of death
|
gender
|
Gender
|
gedcom
|
Returns the gedcom
|
Example
| Request |
require_once('includes/SOAP.php');
$url = 'http://www.example.com/genservice.php?wsdl';);
$wsdl = newSOAP_WSDL($url);
$soap = $wsdl->getProxy();
$auth = $soap->Authenticate('testuser','pass','presidents.ged','none');
$ga = $soap->getDescendants($auth->SID,'I10',2,true);
|
| Response |
...
<ns4:getDescendantsResponse>
<results xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="ns4:Person[3]" SOAP-ENC:offset="[0]">
<item>
<PID xsi:type="xsd:string">I10</PID>
<gedcomName xsi:type="xsd:string">Anne /Pope/</gedcomName>
<birthDate xsi:nil="true"/>
<birthPlace xsi:nil="true"/>
<deathDate xsi:type="xsd:string">1667/1668</deathDate>
<deathPlace xsi:type="xsd:string">Westmoreland Co.,VA</deathPlace>
<gender xsi:type="xsd:string">F</gender>
<gedcom xsi:type="xsd:string">0 @I10@ INDI
1 NAME Anne /Pope/
2 GIVN Anne
2 SURN Pope
2 _MARNM Anne /Washington/
1 SEX F
1 DEAT
2 DATE 1667/1668
...
</gedcom>
</item>
<item>
<PID xsi:type="xsd:string">I5</PID>
<gedcomName xsi:type="xsd:string">Lawrence /Washington/</gedcomName>
<birthDate xsi:type="xsd:string">SEP 1659</birthDate>
<birthPlace xsi:type="xsd:string">Westmoreland Co.,Virginia</birthPlace>
<deathDate xsi:type="xsd:string">FEB 1697/1698</deathDate>
<deathPlace xsi:type="xsd:string">Warner Hall,Gloucester Co.,Virginia</deathPlace>
<gender xsi:type="xsd:string">M</gender>
<gedcom xsi:type="xsd:string">0 @I5@ INDI
1 NAME Lawrence /Washington/
2 GIVN Lawrence
2 SURN Washington
1 SEX M
1 BIRT
2 DATE SEP 1659
...
</gedcom>
</item>
<item>
<PID xsi:type="xsd:string">I3</PID>
<gedcomName xsi:type="xsd:string">Augustine /Washington/</gedcomName>
<birthDate xsi:type="xsd:string">1693/1694</birthDate>
<birthPlace xsi:type="xsd:string">Wakefield,Westmoreland Co.,Virginia</birthPlace>
<deathDate xsi:type="xsd:string">12 APR 1743</deathDate>
<deathPlace xsi:type="xsd:string">Ferry Farm,King George Co.,Virginia</deathPlace>
<gender xsi:type="xsd:string">M</gender>
<gedcom xsi:type="xsd:string">0 @I3@ INDI
1 NAME Augustine /Washington/
2 GIVN Augustine
2 SURN Washington
1 SEX M
1 BIRT
2 DATE 1693/1694
...
</gedcom>
</item>
</results>
</ns4:getDescendantsResponse>
...
|
● getKnownServers -
Retrieves a list of saved servers from the server.
Parameters
Name
|
Description
|
SID
|
Session id that was returned from Authenticate.
|
limit
|
Maximum amount of results to return
|
Returns - ArrayOfServer
Name
|
Description
|
Servers
|
ArrayOfServer (Complex type)
|
name
|
Name given to the server
|
Address
|
URI to the known server
|
Example
Request
|
require_once('includes/SOAP.php');
$url = 'http://www.example.com/genservice.php?wsdl';);
$wsdl = newSOAP_WSDL($url);
$soap = $wsdl->getProxy();
$auth = $soap->Authenticate('testuser','pass','presidents.ged','none');
$gks = $soap->getKnownServers($auth->SID,10);
|
Response
|
...
<ns4:getKnownServersResponse>
<servers xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="ns4:Server[1]" SOAP-ENC:offset="[0]">
<item>
<name xsi:type="xsd:string">http://example.com - clipping.ged.txt</name>
<address xsi:type="xsd:string">http://example.com - clipping.ged.txt</address>
</item>
</servers>
</ns4:getKnownServersResponse>
...
|
● updateRecord -
Updates a record with the provided gedcom
Parameters
Name
|
Description
|
SID
|
Session id that was returned from Authenticate.
|
RID
|
Record ID to update
|
gedcom
|
String of the updated gedcom
|
Returns - String
Name
|
Description
|
message
|
Status message of the result
|
Example
| Request |
require_once('includes/SOAP.php');
$url = 'http://www.example.com/genservice.php?wsdl';);
$wsdl = newSOAP_WSDL($url);
$soap = $wsdl->getProxy();
$auth = $soap->Authenticate('testuser','pass','presidents.ged','none');
$gedcom = '0 @F857@ FAM
1 HUSB @I1749@
1 WIFE @I1750@
1 CHIL @I1751@
1 CHIL @I1752@
1 CHIL @I1753@
1 CHIL @I1754@
1 CHIL @I1755@
1 CHIL @I1768@
1 MARR
2 DATE 21 FEB 2005
2 PLAC Catskill,New York';
$ur = $soap->updateRecord($result->SID, 'F1', $gedcom);
|
| Response |
...
<ns4:updateRecordResponse>
<message xsi:type="xsd:string">
<message xsi:type="xsd:string">Gedcom updated.</message>
</message>
</ns4:updateRecordResponse>
...
|
● checkUpdatesByID -
Checks the record id for updates since the provided date
Parameters
Name
|
Description
|
SID
|
Session id that was returned from Authenticate.
|
RID
|
Record id to check
|
lastUpdate
|
Date of last update
|
Returns - Person
Name
|
Description
|
result
|
Person(Complex Type)
|
PID
|
Person ID
|
gedcomName
|
Person's name in gedcom syntax
|
birthDate
|
Date of birth
|
birthplace
|
Place of birth
|
deathPlace
|
Place of death
|
deathDate
|
Date of death
|
gender
|
Gender
|
gedcom
|
Returns the gedcom
|
Example
Request
|
require_once('includes/SOAP.php');
$url = 'http://www.example.com/genservice.php?wsdl';);
$wsdl = newSOAP_WSDL($url);
$soap = $wsdl->getProxy();
$auth = $soap->Authenticate('testuser','pass','presidents.ged','none');
//get a record that has been updated since 09/13/1999
$cubid = $soap->checkUpdatesByID($result->SID, 'I1', '09/13/1999');
|
Response
|
...
<ns4:checkUpdatesByIDResponse>
<result xsi:type="ns4:Person">
<PID xsi:type="xsd:string">I1</PID>
<gedcomName xsi:type="xsd:string">George /Washington/</gedcomName>
<birthDate xsi:type="xsd:string">11 FEB 1732</birthDate>
<birthPlace xsi:type="xsd:string">Pope's Creek,Westmoreland Co.,Virginia</birthPlace>
<deathDate xsi:nil="true"/>
<deathPlace xsi:type="xsd:string">Mount Vernon, Fairfax Co., Virginia</deathPlace>
<gender xsi:type="xsd:string">M</gender>
<gedcom xsi:type="xsd:string">0 @I1@ INDI
1 NAME George /Washington/
2 GIVN George
2 SURN Washington
1 SEX M
1 BIRT
2 DATE 11 FEB 1732
...
</gedcom>
</result>
</ns4:checkUpdatesByIDResponse>
...
|
Example
| Request |
require_once('includes/SOAP.php');
$url = 'http://www.example.com/genservice.php?wsdl';);
$wsdl = newSOAP_WSDL($url);
$soap = $wsdl->getProxy();
$auth = $soap->Authenticate('testuser','pass','presidents.ged','none');
//get a record that has been updated since 09/13/2005
$cubid = $soap->checkUpdatesByID($result->SID, 'I1', '09/13/2005');
|
| Response |
...
<ns4:checkUpdatesByIDResponse>
<result xsi:type="ns4:Person">
<faultstring xsi:type="xsd:string">
Update check performed but no update was made
</faultstring>
<faultcode xsi:type="xsd:string">
perform_update_check
</faultcode>
</result>
</ns4:checkUpdatesByIDResponse>
... |
Copyright © 2009 PhpGedView Team Members
|
|
