Once the desired database or group of databases has been found. A PDsearch request can be submitted to ...well, search it. This is an example of a search request on a group of databases.
Lets take a look at the composition of a PDsearch request.
http://demosrch.publicdata.com
- This is the servername. Again we are using demo for this tutorial but you will use one of the searchservers provided to you when you
logged in for the day.
pdsearch.php
- since we are performing a search from the publicdata system we call pdsearch.php
input=grp_cri_advanced_name|name
- input is the parameter name for the group or database that you wish to perform a search on. Add '|name' to search for names or '|main' to search for everything else including names. For example, input=grp_cri_advanced_name|main.
type=advanced
- This is the search type that we wish to perform on this database.
asiname=name
- This is the sub-type of type advanced that we wish to perform on this database. There may be other
search sub-types available for this group.
p1=smith
- According to the
search sub-types description a name (advanced) search's p1 is anything related to a name.
matchany=all
- Filter the result and make sure each record must contain all the words typed in. To filter for records that maches any word, use matchany=any.
dlnumber=DOCS
- this is same username that you logged in with.
id=DOCS
- This is your accounts daily id number that we obtained when we logged in for the day.
disp=XML
- This is the display format that we wish to recieve. Since we are an API user this will be XML.
Note: We use GET requests in the tutorial but the parameter can be sent using POST.
This should be done if the length of the request exceeds the 255 character limit.
Here is the response from that request.
Now Lets break down the XML level by level. The Attributes are in blue.
searchdata
Description:
This node is meant to contain data specific to this search request.
Path:
pddata->searchdata
Attributes:
type - The type of search this search performed. ex. name
title - This is the human readable title for the database or group of databases.
dbcount - The number of databases this searched through.
db - The identifying name of the database/group searched.
ed - The edition of data source that was searched. This number could be an incremental number or timestamp.
userinput
Description:
This is a list of the parameters that the user entered to search.
Path:
pddata->searchdata->userinput
Attributes:
searchstring - This is the composed string we made to perform the search.
p1
Description:
The input parameters.
Path:
pddata->searchdata->userinput->p1
searchgroup
Description:
The identifying name of the database/group searched.
Path:
pddata->searchdata->searchgroup
dispfields
Description:
This is the info about the 'columns' from the search results.
Path:
pddata->searchdata->dispfields
disp_fld1
Description:
The first 'column' title.
Path:
pddata->searchdata->dispfields->disp_fld1
Attributes:
format - This format is the default it means that we do nothing to the info in this field.
disp_fld2
Description:
The second 'column' title.
Path:
pddata->searchdata->dispfields->disp_fld2
Attributes:
format - The date format means that the data in the second field in the results is a date. We may or may not care.
source
Description:
The third 'column' title. It is for the source of the result record.
Path:
pddata->searchdata->dispfields->source
Attributes:
format - The source format means that the data here should be formatted as if it were a data source. We may or may not care.
searchpages
Description:
This node contains data about precalculated search pages. This is provided to allow the user to skip around a search.
Path:
pddata->searchdata->searchpages
Attributes:
curpage - This tells you what page you are currently viewing.
page
Description:
These nodes contain the information to jump to this page.(you should also pass the edition forward to eliminate conflicts with database updates.)
Path:
pddata->searchdata->searchpages->page
Attributes:
pagenum - This is the page that is searchmoreid relates to. (These are Entirely generated by the page parameter passed to the request. An API customer should be aware that this is simply a list of the next 10 pages searchmoreids, if available)
searchmoreid - This is the id for a page within a search result. It depends on the search input, the database name and the database edition. Omitting the edition will default to the current edition. This means that if you omit the edition number and a new edition is published the searchmoreid's will become invalid.
results
Description:
This is where the actual search results will be.
Path:
pddata->results
Attributes:
ismore - Either true or false. It is a flag for showing whether or not there are more search results after this list.
searchmoreid - This is the searchmoreid for the next page after this list.
numrecords - The number of records in the results node.(does not account for matching result on other pages)
record
Description:
This represents a single search result and is well... a record
Path:
pddata->results->record
Attributes:
rec - This is the record number to use to link the a detail view of this record.
db - This is the database to use for the detail view.
ed - This is the edition to use for the detail view.
disp_fld1
Description:
A User readable text node. This corresponds to the first column.(Often it will be a name)
Path:
pddata->results->record->disp_fld1
disp_fld2
Description:
A User readable text node. This corresponds to the Second column.(Often it will be a date)
Path:
pddata->results->record->disp_fld2
disp_fld3
Description:
A User readable text node. This corresponds to the third column. Sometimes there are no disp_fld3.
Path:
pddata->results->record->disp_fld3
source
Description:
A User readable text node. This corresponds to the Last column. It will alway be a short title of the database that this record is from.
Path:
pddata->results->record->source
Filters
Some databases optionally have a date of birth filter. You can specify each record to match a date of birth as follows.
What are the parameters to pass in for the optional date of birth filter? In addition, to the previous parameters, please add in any combination of month,day, and year.
month=06
- This is the optional month of birth.
day=10
- This is the optional day of birth.
year=1941
- This is the optional year of birth.
Here is the response from that request.
PublicData API Documentation