GEDCOM SOAP Web Service API

From PGVWiki
Jump to: navigation, search

Introduction

UNDER CONSTRUCTION from web site http://www.phpgedview.net/devdocs/webservice_api.php which is being deprecated.

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: You can test if this documentation is out of date, by examining what is documented in the WSDL. To get the WSDL try this for a default apache or IIS PHPGEDVIEW setup: http://localhost/pgv/genservice.php?wsdl Also note that if you first use the ServiceInfo method below, you can glean enough information to use many of the other methods. Some of the useful information that you can get are things like the list of names of gedcom files, which you can then use with other methods.

           //Test PHPGEDView Web Services
           localhost.GenealogyService ws = new TestPHPGedViewWS.localhost.GenealogyService();
           localhost.serviceInfoResult siResult = ws.serviceInfo();
           foreach (localhost.GedcomInfo gedInfo in siResult.gedcoms)
           {
               Console.WriteLine("ID = " + gedInfo.ID + " and Title = " + gedInfo.title + ".");
           }

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 Web Service Functions

● 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>
...

● changeGedcom

   
       
Parameters

Name

Description

                   gedcom
                   The id of the Gedcom to use.
   
       
Returns -
gedcom

Name

Description

               gedcom
               The gedcom to switched from before you invoked the this method.ServiceInfo

● checkUpdates

● checkUpdatesByID

   Checks the record id for updates since the provided date.ServiceInfo.

Parameters

Name

Description

                   SID
                   Session id that was returned from Authenticate.


                   RID
                   Record id to check.
                   lastUpdate
                   Date of last update
   
       
Returns -
authResult

Name

Description

               result
               Person(Complex Type)
               PID
               Person(Complex Type)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: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>
...

● deleteRecord

● 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 <st1:state w:st="on">

</st1:state><ST1:PLACE w:st="on">

                       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"><st1:place w:st="on"></st1:place><ST1:CITY w:st="on">Fredericksburg,<ST1:STATE w:st="on">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

   
       
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>
...

● getFamilyByID

● getGedcomRecord

● 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>
...

● getPersonByID

● getSourceByID

● getVar

● getXref

● search

   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.,<st1:state w:st="on"></st1:state><ST1:PLACE w:st="on">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>
...

 

   </ST1:PLACE></ST1:STATE>

● ServiceInfo

   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>
...

 

   

● 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,<st1:state w:st="on"></st1:state><ST1:PLACE w:st="on">New York';
$<st1:city w:st="on"></st1:city><ST1:PLACE w:st="on">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>
...