GEDCOM REST Web Service API

From PGVWiki
Jump to navigation Jump to search

This page is under construction

Table of Contents

Introduction

The CGI gedcom access protocol provides a means whereby remote clients can access and manipulate genealogical data stored in phpGedView. This document describes the protocol remote clients use to communicate with phpGedView version .

A client communicates by making a POST or GET request to phpGedView through the file client.php. Every request must include an "action". An "action" tells phpGedView what type of request you want to make. The file client.php will respond with the string "SUCCESS" on the first line followed by the requested information or it will return an error message. Error messages always take the following form:

ERROR #: Error Message

Error message example:

ERROR 1: No action specified.

You may use the "version" and "listgedcoms" actions without a connection. All other actions require that you first send a "connect" action. The "connect" action can take a username and password if you want to have full access, or it can connect anonymously. A successful "connect" action will respond with a session name and session id that must accompany all future requests. You can specify which gedcom you want to work with at any time by sending the optional "ged" parameter with any request. All subsequent requests will use this gedcom until another "ged" parameter is specified.

The "actions" available through the protocol, their required parameters, and their responses are listed in the table below: ([tab] represents a single tab character)

Protocol Actions

From the browser window, or from a tcp/ip connection you will need to type in an action followed by the command such as:

http://localhost/pgv/client.php?action=version

or

http://localhost/pgv/client.php?action=connect

For any command you can run a GET on you can also use a POST on. See the tables below for more detailed list of commands.

version

Protocol Actions

"version" Action Request

"version" Action Response
Get the PhpGedView version.
               

               Required Parameters:
action=version

Sample URL:
client.php?action=version

 Returns the version for this installation of PhpGedView.

Successful Response:
SUCCESS
version number

               Sample Response:

SUCCESS
4.1.6 svn
 

listgedcoms

"listgedcoms" Action Request

"listgedcoms" Action Response
Get a list of all of 
               the gedcoms available on this server.  Could be used to
allow the user to switch between gedcoms.

Required Parameters:
action=listgedcoms
sessionname=sessionid

Sample URL:
client.php?action=listgedcoms
&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

 Returns a tab delimited 
               list of gedcom files and their corresponding titles.  Each
gedcom is written on its own line.

Successful Response:
SUCCESS
gedcomfile1 [tab] title1
gedcomfile2 [tab] title2
...

Sample Response:
SUCCESS
surname.ged [tab] Surname Genealogy
myfamily.ged [tab] My Family History
 

connect

"connect" Action Request

"connect" Action Response
Initiates a session 
               with the server.

               

               Required Parameters:

               action=connect

               
Optional paramters:

               username=username

               password=password

               ged=gedcom.ged
readonly=1

If no gedcom is specified with the "ged" parameter then the default gedcom defined by the PhpGedView system administrator will be used.

If no username and password are sent, then an anonymous read-only connection will be established. Any attempts to change the data will result in an error.

If the "readonly" parameter is sent, then all editing features will be disabled and they will return errors.

Sample URL:
client.php?action=connect&username=admin&password=adminpass&ged=gedcom.ged
Sample Anonymous Read-only connection: client.php?action=connect&ged=gedcom.ged

 Returns the session name and session id for this connection.

Successful Response:
SUCCESS
sessionname [tab] sessionid

                   Sample Response:

               SUCCESS
PHPSESSID [tab] f0c56ab7e2381cf17ce7c94135c1398b
 

get

"get" Action Request

"get" Action Response
Get one or more gedcom 
               records with the given "xref" ids from the gedcom file. 
               The "xref" parameter accepts a semicolon delimetted list of xref
ids.

Required Parameters:
action=get
xref=gedcomid
sessionname=sessionid

Sample URL (single xref):
client.php?action=get&xref=I100
&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

Sample URL (multiple xref):
client.php?action=get&xref=I100;I101
&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

 Returns the raw gedcom record for the given "xref".

Successful Response:
SUCCESS
gedcom records
...

Sample Response:
SUCCESS
0 @I100@ INDI
1 NAME Given Names /Surname/
1 GIVN Given Names
1 SURN Surname
1 BIRT
2 DATE 1 Jan 1900
2 PLAC New York, New York, USA
0 @I101@ INDI
1 NAME Sibling /Surname/
1 BIRT
2 DATE 1 Jan 1902
2 PLAC New York, New York, USA
...
 

getxref

"getxref" Action Request

"getxref" Action Response
Get the first, last, 
               next, or previous xref in the given type list.  A position
               of "new" will create a new GEDCOM record for the given type. 
A position of "all" will return a list of all

Required Parameters:
action=getxref
type=INDI|FAM|SOUR|REPO|NOTE|OBJE|OTHER
position=new|first|next|prev|last|all
xref=gedcomid
sessionname=sessionid

Sample URL: (get the first FAM)
client.php?action=getxref&type=FAM&position=first
&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

Sample URL: (get the next INDI after I100)
client.php?action=getxref&type=INDI&position=next&xref=I100
&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

Sample URL: (get the xref for a new FAM. See also the "append" action)
client.php?action=getxref&type=FAM&position=new
&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

 Returns a list of xref

               Successful Response:

               SUCCESS

               XREF
...

Sample Response:
SUCCESS
I102
...
 

getvar

"getvar" Action Request

"getvar" Action Response
Get the value of the 
               given global phpGedView variable.  A list of available
variable names can be found in the config_gedcom.php file.

Required Parameters:
action=getvar
var=variablename
sessionname=sessionid

Sample URL:
client.php?action=getvar&var=GEDCOM
&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

 Returns the value of the global variable specified in "var".

Successful Response:
SUCCESS
variable value

Sample Response: (in this example the current working gedcom)
SUCCESS
surname.ged
 

update

"update" Action Request

"update" Action Response
Update a GEDCOM record by replacing it by the given gedcom record.

Required Parameters:
action=update
xref=gedcomid
gedrec=Raw GEDCOM Record
sessionname=sessionid

Sample URL:
client.php?action=update&xref=I100
&gedrec=0 @I100@ INDI\n1 NAME New Name /Surname/\n
&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

 Returns "SUCCESS".

               Successful Response:
SUCCESS

Sample Response:
SUCCESS
 

append

"append" Action Request

"append" Action Response
Append a new GEDCOM record to this gedcom file.  (See also action=getxref&position=new)

Required Parameters:
action=append
gedrec=raw GEDCOM record
sessionname=sessionid

Sample URL:
client.php?action=append&gedrec=0 @NEW@ INDI\n1 NAME New Name /Surname/\n&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

 Returns "SUCCESS" and the new xref assigned to this gedcom record.

Successful Response:
SUCCESS
XREF

Sample Response:
SUCCESS
I9999
 

delete

"delete" Action Request

"delete" Action Response
Deletes the GEDCOM record from the file.

Required Parameters:
action=delete
xref=gedcomid
sessionname=sessionid

Sample URL:
client.php?action=update&xref=I100
&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

 Returns "SUCCESS".

               Successful Response:
SUCCESS

Sample Response:
SUCCESS
 

getnext

"getnext" Action Request

"getnext" Action Response
Get the next gedcom record after the given "xref" from the gedcom file.

Required Parameters:
action=getnext
xref=gedcomid
sessionname=sessionid

Sample URL:
client.php?action=getnext&xref=I100
&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

 Returns the raw gedcom record after the given "xref".

Successful Response:
SUCCESS
gedcom record

Sample Response:
SUCCESS
0 @I99@ INDI
1 NAME Given Names /Surname/
1 GIVN Given Names
1 SURN Surname
1 BIRT
2 DATE 1 Jan 1880
2 PLAC New York, New York, USA
 

getprev

"getprev" Action Request

"getprev" Action Response
Get the previous gedcom record before the given "xref" from the gedcom file.

Required Parameters:
action=getprev
xref=gedcomid
sessionname=sessionid

Sample URL:
client.php?action=getprev&xref=I100
&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

 Returns the raw gedcom record before the given "xref".

Successful Response:
SUCCESS
gedcom record

Sample Response:
SUCCESS
0 @I101@ INDI
1 NAME Given Names /Surname/
1 GIVN Given Names
1 SURN Surname
1 BIRT
2 DATE 1 Jan 1920
2 PLAC New York, New York, USA
 

search

"search" Action Request

"search" Action Response
Use regular expressions to search gedcom INDI records.

Required Parameters:
action=search
query=keyword or expression
sessionname=sessionid

Sample URL: (search for all indis with "arizona" in their record)
client.php?action=search&query=arizona
&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

Sample URL: (search for all indis with an event in 1900)
client.php?action=search&query=DATE+.*+1900
&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

 Returns a sorted list of INDI xrefs.

Successful Response:
SUCCESS
XREF
...

Sample Response:
SUCCESS
I1
I100
I102
...
 

soundex

"soundex" Action Request

"soundex" Action Response
Use soundex to search INDI names.

Required Parameters:
action=soundex
firstname=givenames
lastname=lastname
sessionname=sessionid

Sample URL: (search for indis with soundex surname matching "finlay")
client.php?action=soundex&lastname=finlay
&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

Sample URL: (search for indis with soundex surname matching "finlay" and firstname matching "john")
client.php?action=soundex&lastname=finlay&firstname=john
&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

 Returns a sorted list of INDI xrefs.

Successful Response:
SUCCESS
XREF
...

Sample Response:
SUCCESS
I1
I100
I102
...
 

uploadmedia

"uploadmedia" Action Request

"uploadmedia" Action Response
Upload media files to 
               the PhpGedView server.  You can specify either a "mediafile"
a "thumbnail" or both.

Required Parameters:
action=uploadmedia
mediafile=[File Data]
thumbnail=[File Data]
sessionname=sessionid

Sample URL:
This cannot be done through a GET.  The data must be posted in Multi-part mime form data.

 

 Returns a URL to the uploaded object.

Successful Response:
SUCCESS
http://www.yoursite.com/phpGedView/media/object
http://www.yoursite.com/phpGedView/media/thumbs/object

Sample Response:
SUCCESS
http://www.yoursite.com/phpGedView/media/object
 
 

getchanges

"getchanges" Action Request

"getchanges" Action Response
Get a list of changes since the given date. 

Required Parameters:

               action=getchanges

               date=DD MMM YYYY
sessionname=sessionid

Sample URL:
client.php?action=getchanges&date=1+FEB+2006 &PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

Returns a list of the changed record XREFs.

Successful Response:
SUCCESS
I101
I102
F51

 
 

Sample Communications

Sample Communication
The following is an example communication:

CLIENT:
client.php?action=connect&username=admin&password=adminpass

SERVER:
PHPSESSID [tab] f0c56ab7e2381cf17ce7c94135c1398b

CLIENT:
client.php?action=getvar&var=PEDIGREE_ROOT_ID&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

SERVER:
I1

CLIENT:
client.php?action=get&xref=I1&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

SERVER:
0 @I1@ INDI
1 NAME Given Names /Surname/
1 GIVN Given Names
1 SURN Surname
1 BIRT
2 DATE 1 Jan 1900
2 PLAC New York, New York, USA
1 FAMS @F1@

CLIENT:
client.php?action=get&xref=F1&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

SERVER:
0 @F1@ FAM
1 HUSB @I1@
1 WIFE @I2@
1 MARR
2 DATE 13 Jun 1921
2 PLAC New York, New York, USA
1 CHIL @I3@

(The next few requests show how to switch from one gedcom to another)
CLIENT:
client.php?action=listgedcoms&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

SERVER:
surname.ged [tab] Surname Genealogy
myfamily.ged [tab] My Family History

CLIENT: (notice the GEDCOM parameter)
client.php?GEDCOM=myfamily.ged&action=getvar&var=PEDIGREE_ROOT_ID
&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

SERVER:
I103

CLIENT:
client.php?action=get&xref=I103&PHPSESSID=f0c56ab7e2381cf17ce7c94135c1398b

SERVER
0 @I103@ INDI
1 NAME Given Names /Surname/
1 GIVN Given Names
1 SURN Surname
1 BIRT
2 DATE 1 Jan 1976
2 PLAC Hamburg, Germany
1 FAMS @F1@

 

Errors

ErrorDescription
ERROR 1: No action specified. You will receive this error if no action was given on the URL. You can also receive this error if the URL is malformed.
ERROR 2: Unable to process request. Unknown action. You will get this error when the action supplied is not one of the valid actions.
ERROR 3: No gedcom id specified. Please specify a xref. You will get this error if you attempted to use an action that requires an xref parameter, but failed to supply the xref parameter on the URL.
ERROR 4: Could not find gedcom record with xref The xref ID you specified does not match any record in this gedcom.
ERROR 5: GEDCOM file is not writable. Unable to complete request. You will get this error if the appropriate write permissions have not been set on the gedcom file on the filesystem.
ERROR 6: Unable to open GEDCOM file resource. Unable to complete request. This error should be very rare and will only happen if the operating system on the server is unable to open the gedcom file for some reason.
ERROR 7: Unable to write to GEDCOM file. This error should be very rare and will only happen if the operating system on the server is unable to write to the gedcom file. Possible reasons could be that another user on the system has the file open.
ERROR 8: No gedcom record provided. Unable to process request. You will receive this error when the action requires that you provide a full gedcom record but no 'gedrec' parameter was found in the request.
ERROR 10: Username and password key failed to authenticate. The username and password supplied for the connect command failed to authenticate. This means that the password was incorrect or the username is invalid.
ERROR 11: No write privileges for this record. You will receive this error if you try to edit a record that you don't have permission to edit, or if you try to edit in read-only mode.
ERROR 12: use 'connect' action to initiate a session. You will receive this error if you try to use an action without first using the 'connect' action. You can also receive this error if your session timed out.
ERROR 13: Invalid variable specified. Please provide a variable. You will get this error during the 'getvar' action if the variable name supplied in the 'var' parameter is not a valid variable.
ERROR 15: No query specified. Please specify a query. This error means that you did not send a 'query' parameter with the 'search' action.
ERROR 16: No names specified. Please specify a firstname or a lastname. You will receive this error if the 'firstname' and 'lastname' parameters are missing in the 'soundex' action.
ERROR 17: Unknown position reference. Valid values are first, last, prev, next. This error occurs when and invalid 'position' parameter was sent during the 'getxref' action.
ERROR 18: Invalid $type specification. Valid types are INDI, FAM, SOUR, REPO, NOTE, OBJE, or OTHER You will get this error in the 'getxref' action if the 'type' parameter is not one of the valid gedcom types.
ERROR 19: Upload Error You will get an ERROR 19 if an error occured during the file upload for the "uploadmedia" action.
ERROR 20: Invalid GEDCOM 5.5 format. You will recieve this error if you supplied a gedcom record that does not have the basic structure of a level 0 gedcom record
ERROR 21: No Gedcoms available on this site. This error occurs if you are trying to connect to a PhpGedView site that does not have any Gedcoms imported.
ERROR 22: Gedcom [$GEDCOM] needs to be imported. This error occurs if you are trying to access a gedcom that has not yet been imported in PhpGedView.
ERROR 23: Invalid date parameter. Please use a valid date in the GEDCOM format DD MMM YYYY. This error occurs if you have sent and invalid date. Dates should be specified using the GEDCOM 5.5 standard.



Copyright © 2008 PhpGedView Team Members
Retrieved from "https://wiki.phpgedview.net/en/index.php?title=GEDCOM_REST_Web_Service_API&oldid=11928"