Build with HistoryLines

Create insightful and engaging personal history apps. Integrate HistoryLines content into your family tree, timelines, and educational tools to create amazing story experiences.
Sign in

Getting Started

This HistoryLines API provides easy access to HistoryLines data and features to integrate into applications and websites.

The API is based on the REST architecture, and all API calls return JSON objects.

Every API request requires a valid access key, managed in your account, added to the REST request as a parameter "key".

Getting Story Content

Endpoint: https://historylines.com/api/v1/story
Returns: list of matching story snippets: place descriptions, lifestyle dimensions, and events.

Parameters

first_name Required.
middle_name Optional
last_name Required.
birth_date Required. Used to determine age in telling the story. Also used as the start date for time range if no "start_date" parameter is provided. Most date formats accepted
start_date Optional. Start date of the time range. If not included, birth_date is used as start_date. Most date formats accepted
end_date Required. End date of the time range. Time range cannot exceed 120 years. Most date formats accepted
place Required. Free text. Will be transformed and standardized to match with content.
gender Required. 'M' or 'F'

Results

{
		  "request": {
		    "first_name": "...",
		    "end_date": "...",
		    "birth_date": "...",
		    "middle_name": "...",
		    "last_name": "...",
		    "gender": "...",
		    "place": "...",
		    "start_date": "...",
		    "key": "..."
		  },
		  "data": [
		    {
		      "location_code": "...",
		      "age": "...",
		      "impact_id": "...",
		      "impact_score": "...",
		      "start_date": "...",
		      "end_date": "...",
		      "caption": "...",
		      "headline": "...",
		      "snippet": "...",
		      "type": "..." 
		    }
		  ],
		  "ping_id": "...",
		  "code": "200",
		  "msg": "Success"
		}

Response Codes

200Successful request
300Access key not found
301Access key not valid
302Access key not active
303Access key limit usage reached
360Parameter not valid
370Required parameter not found
400Error processing request

Reusing Story Content

Endpoint: https://historylines.com/api/v1/ping
Returns: response code and message acknowledging the reuse of content

Parameters

ping_id Required. This is provided in your request for new content.
pixel Optional. If set pixel=1, the result will be a 1x1 pixel instead of JSON.

Results

{
		  "code": "200",
		  "msg": "Success"
		}

Response Codes

200Successful request
300Access key not found
301Access key not valid
302Access key not active
303Access key limit usage reached
370Required parameter not found
400Error processing request

Terms of Use for HistoryLines API

Overview

We believe that history is a key element in telling the story of a person's life. The HistoryLines API is intended to allow developers, companies, and partners to build engaging and insightful products and stories about our ancestors.

Copyright

All HistoryLines is copyright HistoryLines.com, and HistoryLines maintains all rights to that content, except as where expressly attributed. Usage of the API does not transfer rights or ownership of the content.

Restrictions

Access to the API is free to approved developers, intended for prototyping applications that use HistoryLines content. The following free access restrictions are enforced:
- No more than 50 API calls per 24 hours (rolling).
- The number of results are truncated.
- The content in the results is truncated.

Contact us for full access to the API.

Responsibilities

- You must not violate any law or the rights of any individual or entity.
- You must not impersonate HistoryLines, or attempt to collect HistoryLines email addresses and passwords.
- You must not attempt to circumvent restrictions and limitations enforced by the API.

Storing and Using Data

- You may not store any of the data you receive from HistoryLines, unless you have expressed, written consent.
- You must not write apps that attempt to harvest HistoryLines data systematically.

Communications

We may periodically communicate with developers regarding additions and changes to the API, changes to API policies, and other API-related issues. Please make sure your email address associated with your developer account is current so as not to miss important communications.

Enforcement

We reserve the right to enforce all the terms of use for the API, including restricting access, disabling accounts, legal action, or any other action we deem appropriate at our sole discretion.

Changes

We may change these terms without prior notice at any time. Your continued use of the HistoryLines API constitutes your acceptance of these changes.
» Saving and Printing the Story
Subscribers can download and print the story, by clicking on the "Save and Print" link on the story page. This will generate the PDF and open it in a window, where you can save or print.
» Adding Immigration
  1. On the story, click "Add to Story"
  2. Click "Add Immigration/Relocation"
  3. Enter the details, and click "Save"
» Adding a Residence
  1. On the story, click "Add to Story"
  2. Click "Add Residence"
  3. Enter the details, and click "Save"
» Add a Child, Spouse, Sibling
To add a child, spouse, or sibling to a person on the family tree:
  1. Center that person on the tree, by clicking on the (tree) icon.
  2. Click on "Add Spouse", "Add Child", or "Add Sibling"
» Delete a Tree
To delete a family tree:
  1. On the "Stories" page, click on the tree to open the tree
  2. Click on the edit (pencil) icon, and then "Delete this Tree"
» Edit a Person on the Tree
To edit the information of a person on the tree, click on the person's box. This will open the edit form. Make any changes, then click "Save and Close".
» Remove a Story Section
  1. On the story, click "Edit" on the section you wish to remove
  2. Click "Hide this from the story"
» Dots on Children and Spouses
The dots on spouses and children help to indicate the link between the parent and the child. A person may have multiple spouses, and multiple children from each spouse. The color of the dots links the child to the parent.
» Add a Nickname
If your ancestor had a nickname or a given name that is preferred to be used in the story, you can add a nickname to the person:
  1. Click on the person on the family tree
  2. Click on the "Add Nickname" link
  3. Add the nickname, then click "Save and Close"
Viewing the story will now show the preferred nickname in the narrative.
» How Do I Subscribe?
Visit the Subscribe page to learn about pricing, options, and to subscribe.
» Sharing on Facebook
Stories are easy to share on Facebook. On the story page, click on the "Share" button, then the Facebook icon. This will share the story page, and create an picture of the story to be shared. The Facebook link will link to the story page on HistoryLines.
» Sharing on Blogs
There are two ways to share on a blog:
  1. PREVIEW. Post a preview image of the story, linking to the full story on HistoryLines. This is a snapshot view of the story, which will not change.
  2. EMBED. Embed the story in an iframe on your blog. This will be a live version of the story, which will automatically update as you edit it on HistoryLines.
Instructions for both of these options are found on the "Share" link on the story page.
» Finding People on a Tree

Whether you imported a large GEDCOM file, or built a large tree, you can easily search the tree to find ancestors you are interested in. The search field is right below the name of the tree on the "Trees" page.


Matching ancestors will automatically appear as you type. Clicking on a matching name will load the tree with them at the center. To make an individual the permanent starting point for the tree, click on the person, then "Set as Tree Starting Point".

» Importing a tree from Ancestry
First, export your tree from Ancestry as a GEDCOM file. On Ancestry.com, go to your Tree Settings (in the drop-down menu under your tree name) and in the Tree info tab, look over to the right where it says Manage your tree. Click on Export tree. Once you have downloaded the GEDCOM file from Ancestry, you can import it into HistoryLines. On the "Stories" page, click on "Import a GEDCOM File", then select the file, name it, and click "Upload GEDCOM". HistoryLines will then create your family tree from that GEDCOM file.
» Importing a tree from MyHeritage

First, export your tree from MyHeritage as a GEDCOM file. Click here: Instructions


Once you have downloaded the GEDCOM file from MyHeritage, you can import it into HistoryLines. On the "Stories" page, click on "Import a GEDCOM File", then select the file, name it, and click "Upload GEDCOM". HistoryLines will then create your family tree from that GEDCOM file.

» Importing a tree from FamilySearch
HistoryLines can import your tree directly from FamilySearch. On the "Stories" page, click on "Import from FamilySearch". You will be directed to the FamilySearch login page, to sign in, then back to HistoryLines, which will automatically download your family tree into HistoryLines.
Any time you make changes to your tree on FamilySearch, come back to HistoryLines, go to your family tree, click on the person you wish to update, then click on "Update from FamilySearch". The person will be updated with the latest information from FamilySearch.
» Arranging Photos in Story Sections
Each story section can contain up to 10 photos. You can re-arrange, rotate, delete, and add photos on the "Edit" or "Personalize" on any story section. The first photo in the list will display as the large photo in the story. You can also add captions that will appear in the large view, and in the exported PDF.
» Importing a tree from RootsMagic, Family Tree Builder, and other software

First, export your tree from your software problem as a GEDCOM file. (See your software guide for instructions)


Once you have downloaded the GEDCOM file from your software program, you can import it into HistoryLines. On the "Stories" page, click on "Import a GEDCOM File", then select the file, name it, and click "Upload GEDCOM". HistoryLines will then create your family tree from that GEDCOM file.

» How do I stop a subscription?
Email us if you would like to make changes to your subscription
» How do I update my payment information?
Go to your "Account" page, click on "Payment Information", then make any needed changes.
Intro
Tree Basics
X
Importing from FamilySearch Importing GEDCOM Creating PDF
Ancestors
Siblings
Spouses
Children
You can leave this page while GEDCOM file is imported.