Roadtrippers Developer Hub

Welcome to the Roadtrippers Developer Hub. You'll find comprehensive guides and documentation to help you start working with Roadtrippers as quickly as possible, as well as support if you get stuck. Let's jump right in!

Exports

Export data from Boone.

Users who are managing a significant amount of custom data in the Boone platform may wish to export all of that data in bulk. The Exports API provides several endpoints to manage these kinds of bulk data exports.

🚧

Account Setup Required

If you want to use these features, please contact your account manager or [email protected] to ensure that you have correct AWS permissions for S3 access.

/api/v2/exports/:export_id

Check the status of the export corresponding to a given export id.

Returns

status: 200

{
  "data": {
    "id": 8,
    "started_at": "2016-12-16T13:27:52.149Z",
    "completed_at": null,
    "files": [
      {
        "file_url": "s3://bucket/data_file.json",
        "item_type": "places",
        "format": "json",
        "completed_at": null,
        "error_text": null,
        "completed_count": 0,
        "item_count": 10
      }
    ],
    "directives": [
      {
        "format": "json",
        "item_type": "places",
        "opts": null
      }
    ]
  }
}

Exports are queued and completed asynchronously. The more data in the export, the longer it will take to complete. Progress is indicated by both the started_at timestamp and the completed_at values in the files array.

You can begin fetching files from an export as soon as a file is completed (ie. when completed_at on an individual file is not null). Note that the item_count and completed_count should be identical, and error_text should be null in a successful export.

The data.completed_at field will show a timestamp indicating the overall completion time for the export. Each file in the files array also indicates a completed_at timestamp.

Items are split at 10,000 records per file. The files array specifies each file and notes the status of each file processed.

/api/v2/exports

Create a new export.

Exports are available in [two formats]((https://docs.boone.ai/docs/data-formats): CSV and JSON.

Depending on the data of interest, there are several types of exports: tags, places, and canonical_places. Parameters under directives differ by the item_type.

Specifying the source_id is required for all exports. This value should have been provided with your API credentials.

Export Tags

Exports your custom tags, and an associated mapping to internal Boone tags.

To export tags, specify "tags" as item_type and choose the format (csv or json).

Tags Export Example

{
  "export": {
    "source_id": 8,
    "directives": [
     { 
        "item_type": "tags", 
        "format": "json" 
      }
    ]
  }
}

Export Places

Exports your custom place data, as provided to Boone.

To export custom place data, specify "places" as item_type and choose the format (csv or json).

Places Export Example

{
  "export": {
    "source_id": 8,
    "directives": [
     { 
        "item_type": "places", 
        "format": "json" 
      }
    ]
  }
}

Export Canonical Places

Exports place data from all of Boone.

For starters, specify "canonical_places" as the item_type.

There are several options to consider in exporting Canonical Places: Are you interested in all places, or only the places of which you have linked custom data? Do you want places of a specific region Would you like all, new, updated, or deleted places?

Regional Exports

Limits the data by a geographic region.

Specify opts.region_id to restrict place data for a city, state, country, etc.

To find a region_id value, query the Autocomplete endpoint.

📘

What to expect when limiting by region?

Limiting by region isn't an absolute filter on a city, state, or country. Depending on the data Boone has for a region, the bounds can be defined by a polygon, a radius around a point, or a bounding box. Filtering data from the export files on the client end might be necessary to meet your needs.

Linked / Contributed Places

Consider two places, Terry's Turf Club and Coffee Emporium. Suppose you have imported custom place data that is linked to Terry's Turf Club but are not aware of Coffee Emporium. This linking is indicated by the opts.contributed flag.

An export where opts.contributed = true, will return all the canonical places of which you have linked place data. Terry's Turf Club would be included, in this case.

Alternatively, an export where opts.contributed = false, will return all the canonical places. Terry's Turf Club and Coffee Emporium will be included in this export.

📘

Exports Permissions Notice

Exporting places without linked custom place data (opts.contributed = false) is an account permission and may require contacting your account manager to enable

Exports that use opts.contributed = false require the opts.region_id. This can be provided by your account manager but is also accessible from the Autocomplete API.

Canonical Places Export Example

This example exports all canonical places with linked custom place data that exist in Michigan (region 1835).

{
  "export": {
    "source_id": 8,
    "directives": [
      {
        "item_type": "canonical_places",
        "format": "json",
        "opts": {
          "contributed": true,
          "region_id": 1835
        }
      }
    ]
  }
}

Returns

status: 200

{
  "data": {
    "id": 8,
    "started_at": "2016-12-16T13:27:52.149Z",
    "completed_at": null,
    "files": [
      {
        "file_url": "s3://your-bucket/data_file.json",
        "item_type": "places",
        "format": "json",
        "completed_at": nil,
        "error_text": nil,
        "completed_count": 0,
        "item_count": 10
      }
    ],
    "directives": [
      {
        "format": "json",
        "item_type": "places"
      }
    ]
  }
}

/api/v2/exports

Fetch a list of your exports.

Returns

status: 200

{
  "data": [
    {
      "id": 8,
      "started_at": "2016-12-16T13:27:52.149Z",
      "completed_at": null,
      "files": [
        {
          "file_url": "s3://bucket/data_file.json",
          "item_type": "places",
          "format": "json",
          "completed_at": nil,
          "error_text": nil,
          "completed_count": 0,
          "item_count": 10
        }
      ],
      "directives": [
        {
          "format": "json",
          "item_type": "places"
        }
      ]
    }
  ]
}

Field Definitions

export

NameTypeRequired?Description
idintegerNoDatabase ID of the import.
source_idintegerYesTarget source ID for the import.
started_atstringYesTime that the import was started.
completed_atstringNoTime that the import was completed, if it has been.
filesarray of file objectsYesFiles to be included in the import.

file

NameTypeRequired?Description
item_typestringYesType of data included in import. places and tags supported.
formatstringYesFormat of file to be imported. csv and json supported.
file_urlstringsYesFile to be included in the import.
completed_atstringNoTime that the file was completed, if it has been.
error_textstringNoError information if the file resulted in error.
completed_countintegerYesNumber of total places that have been processed.
item_countintegerYesNumber of total places that will be processed.

Data Formats

JSON Schema
CSV Requirements

Updated 2 years ago

Exports


Export data from Boone.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.