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 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 |
|
"version" Action Request |
"version" Action Response |
Get the PhpGedView version.
Required Parameters:
action=versionSample URL:
client.php?action=version |
Returns the version for
this installation of PhpGedView. Successful Response:
SUCCESS
version number
Sample Response:
SUCCESS
2.65 final |
| |
|
"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" 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=1If 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 |
All following actions require a connection be established before they can be used.
|
|
"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" 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" 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" 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" 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" 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" 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" 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" 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" 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" 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" 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
|
| |
| Error | Description |
|---|
| 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. |
