The Person Finder application stores and exports records using the People Finder Interchange Format (PFIF), which is based on XML. Documentation on the format is available here:

• PFIF 1.3 specification
• PFIF FAQ and implementation guidelines

Requesting access to an Existing Person Finder Instance

To Search or download/upload data from/to an existing Google Person Finder instance, you need an authorization token. Note: This is not required for custom instances you may want to create yourself. This is only required for instances that Google hosts and manages for major disaster events.

• If you are developing an application, you can use our test instance without requesting an API key. This test instance provides search and read access:
• http://google.org/personfinder/test-nokey
• Authorization tokens can be requested here. The three types of access you can apply for are:
• Search: Allows you to retrieve data based on a search query.
• Read: Allows you to retrieve all records in the database.
• Write: Allows you to publish records to the database.

When Google receives a request for a token, we may evaluate the request based on factors including the motivation for the request and the likelihood that the request will meaningfully expand the usefulness of Person Finder and its accessibility to users. Google reserves the right to grant or deny a request for a token for any reason, in its sole discretion. Any entity requesting a token must agree to the Person Finder API Terms of Service.

Downloading data from Person Finder

PFIF 1.3 person and note feeds are available here:

https://www.google.org/personfinder/repository/feeds/person?key=api_key
https://www.google.org/personfinder/repository/feeds/note?key=api_key

By default, these feeds return the most recently added person records or note records in reverse chronological order. These query parameters are supported:

• max_results: Return up to the specified number of results (maximum 200).
• skip: Skip the specified number of records before returning the next max_results results.
• min_entry_date: Return only results with an entry_date greater than or equal to the specified timestamp, which should be in UTC in yyyy-mm-ddThh:mm:ssZ format. If this parameter is specified, results will be returned in forward chronological order.
• person_record_id: Return only notes for this person record. This parameter is only valid for the note feed.

You can use the person_record_id parameter to subscribe to a feed of notes on a specific person.

If you need to keep another database synchronized with the Google Person Finder database, you can use the min_entry_date and skip parameters to download incremental updates. Use the latest entry_date you have previously received from Google Person Finder as the min_entry_date for your first request. Then take the latest entry_date in the batch you receive, and use it as the min_entry_date for your next request. Use the skip parameter to skip the records you already received that have the same entry_date. This algorithm is implemented by tools/download_feed.py.

If you know the PFIF person_record_id of a specific person, you can fetch a single PFIF person record with notes at the following URL:

https://www.google.org/personfinder/repository/api/read?key=api_key&id=person_record_id

When displaying any content accessed via the API to a user, you must display a link to the original source of information to refer any enquiries in connection with that specific record back to the original source, and may not intermix content accessed via the API with other content in any way that makes it unclear which content came from which source.

Using the Person Finder Search API

You can access the search API here:

https://www.google.org/personfinder/repository/api/search?key=api_key&q=your query

It will return the matching results as a XML file with PFIF format. By default it will return up to 100 records. You can use a max_results=Nparameter to restrict the number of result records.

When displaying any content accessed via the API to a user, you must display a link to the original source of information to refer any enquiries in connection with that specific record back to the original source, and may not intermix content accessed via the API with other content in any way that makes it unclear which content came from which source.

Uploading data into Person Finder

You can also push one or more PFIF records to the Person Finder by posting an XML file to the following URL:

https://www.google.org/personfinder/repository/api/write?key=api_key

PFIF 1.1, 1.2, 1.3 are accepted. To obtain an auth_token, you can fill out this form. You will need to tell them which PFIF source domain you will be using the token for, and the token can only be used to upload person records whose person_record_id is prefixed with that domain.

Once you have prepared an XML file, you can use the following command to upload it:

curl -X POST -H 'Content-type: application/xml' --data-binary @your_file.xml \     https://www.google.org/personfinder/repository/api/write?key=auth_token

The XML document can contain <pfif:person> elements with nested <pfif:note> elements. To understand the proper XML format, see the PFIF example document. We recommend that you upload a single record or a small number of records as a test, retrieve the records using the Individual Person Record API (/api/read), and view the records on the site to verify that the results are what you expected. Pay careful attention to the handling of accented letters, note text, source URLs, and photo URLs (if you have them).

Due to the size limitation on POST requests, you should split up files into batches of 100 <pfif:person> elements. If you encounter an error, or need to correct problems in a previous upload, it is safe to upload the same records again. Records will replace existing records with the same person_record_id or note_record_id.

The response will be an XML document like this:

<?xml version="1.0"?>
<status:status>
  <status:write>
    <status:record_type>pfif:person</status:record_type>
    <status:parsed>1</status:parsed>
    <status:written>1</status:written>
    <status:skipped>
    </status:skipped>
  </status:write>

  <status:write>
    <status:record_type>pfif:note</status:record_type>
    <status:parsed>1</status:parsed>
    <status:written>1</status:written>
    <status:skipped>
    </status:skipped>
  </status:write>
</status:status>

Each <status:write> element describes one batch of writes. <status:record_type> indicates the type of the batch. <status:parsed> says how many XML records were successfully parsed. <status:written> says how many were written to the datastore. In the above example, 1 person and 1 note were successfully written. When there are problems it will look like this:

<?xml version="1.0"?>
<status:status>
  <status:write>
    <status:record_type>pfif:person</status:record_type>
    <status:parsed>1</status:parsed>
    <status:written>0</status:written>
    <status:skipped>
      <pfif:person_record_id>google.com/person.4040</pfif:person_record_id>
      <status:error>not in authorized domain: u'google.com/person.4040'</status:error>
    </status:skipped>
  </status:write>

  <status:write>
    <status:record_type>pfif:note</status:record_type>
    <status:parsed>1</status:parsed>
    <status:written>0</status:written>
    <status:skipped>
      <pfif:note_record_id>zesty.ca/note.53</pfif:note_record_id>
      <status:error>ValueError: bad datetime: u'xyz'</status:error>
    </status:skipped>
  </status:write>
</status:status>

Each <status:skipped> entry describes the reason why a particular record was skipped, and includes the record ID if one was given.

When you upload person or note records, you will be replacing any existing records with the same record ID. It should be safe to upload the same data multiple times while you fix formatting problems.

Google will treat all PFIF records submitted through Google Person Finder and through the API in conformance with the PFIF Data Expiry Mechanism.