Difference between revisions of "GEDCOM SOAP Web Service API"

Latest revision as of 21:02, 15 August 2008

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

                   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>

               ...

Difference between revisions of "GEDCOM SOAP Web Service API"

Latest revision as of 21:02, 15 August 2008

Contents

Introduction

API Web Service Functions

● Authenticate

● changeGedcom

● checkUpdates

● checkUpdatesByID

● deleteRecord

● getAncestry

● getDescendants

● getFamilyByID

● getGedcomRecord

● getKnownServers

● getPersonByID

● getSourceByID

● getVar

● getXref

● search

● ServiceInfo

● updateRecord

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Main Links

Documentation

Community

Development

Tools