API Documentation

Approach Guides provides a complete solution for inspiring, informing and converting your customers. Our purpose-built multimedia-content platform delivers hyper-relevant, personalized engagements at all touchpoints: email, website, social and mobile.

The RESTful API makes it easy. The following technical documentation describes the resources that make up the Approach Guides API v1.0

Authentication

To get started using the API, you will need an API Key and Secret. If you don't have any credentials, please contact partner@approachguides.com.

All API endpoints require basic HTTP Authentication with the API Key as the username, and the API Secret as the password. If you recieve 401 Authorization Failed error on a request, the credentials you supplied were invalid.

Responses

All responses are returned in JSON and include an items property which contains all of the data, and a meta property which is explained below.

Response Status Codes

The API will provide a standard HTTP status code on each call, which will be one of the following.

Meta Information

All responses contain a meta property which contains the following values.

Dates and Times

Some endpoints will also return created_at and updated_at properties which contain dates and times relating to when the item was created and when it was last updated. These are Atom formatted dates that include timezone, and can readily be parsed by all coding languages, including Javascript.

Pagination

Requests that return multiple items will be paginated to 15 items by default. Page numbering starts at 1.

To process additional pages of results you must supply a page parameter e.g. ?page=10. To verify this has worked, check the meta.current_page property.

To set the number of items returned per request, you can supply a count paramter e.g. ?count=50. To verify this has worked, check the meta.per_page property.

Sample code

Below is a simple example of how to consume the Approach Guides API with PHP code. Note that your_api_key and your_api_secret should be replaced with your API credentials.

// Connect to API and parse data
$url = "https://your_api_key:your_api_secret@api.approachguides.com/v2/destinations";
$response = file_get_contents($url);
$data = json_decode($response);

// Output the data
var_dump($data);

Destinations

This endpoint returns all destinations.

Example response

{
    "items": [
        {
          "id": 1,
          "parent_id": null,
          "name": "Africa",
          "label": "Africa",
          "depth": 0,
          "created_at": "2016-08-19T17:00:28+00:00",
          "updated_at": "2016-08-19T17:00:28+00:00"
        },
        {
          "id": 2,
          "parent_id": 1,
          "name": "Botswana",
          "label": "Africa > Botswana",
          "depth": 1,
          "created_at": "2016-08-19T17:00:28+00:00",
          "updated_at": "2016-08-21T13:21:51+00:00"
        }
    ]
}

Tags

This endpoint returns all tags.

Example response

{
    "items": [{
        "id": 1,
        "tag": "Approach Guides",
        "created_at": "2016-08-19T17:00:48+00:00",
        "updated_at": "2016-08-21T13:26:52+00:00"
    }]
}

Languages

This endpoint returns all languages.

Example response

{
    "items": [
        {
            "id": 1,
            "name": "English",
            "created_at": "2016-08-19T17:00:29+00:00",
            "updated_at": "2016-08-21T13:26:54+00:00"
        }
    ]
}

Content

This endpoint returns all content available to you.

Endpoints

Optional Parameters

Below are optional parameters that can be used to further tailor the returned data. Parameters should be added to the endpoint as GET parameters, for example, api.approachguides.com/v2/content?with=destinations,tags&languages=1 will return all content with destinations and tags where the language is equal to 1, which is English.

Important Note

In addition to the usual response data, we now return two new properties when you hit /v2/content with ?collection=X where X is one of your collection IDs.

1. To use our analytics, simply swap the current url field: content_url for the new field: content_url_analytics and analytics will start flowing into your dashboard.
2. To display individual content items such that they match the order assigned in “Collections” in the content portal, use the position field, which starts at 0 for the content displayed first and continues 1, 2, 3, etc.

Response data

Example response

{
    "items": [
        {
            "id": 1,
            "title": "Approach Guides for Istanbul",
            "lead_in": "...",
            "synopsis": "...",
            "author": "...",
            "runtime": "...",
            "type_id": 1,
            "content_url": "...",
            "embed_type": "...",
            "level": null,
            "published_at": "2015-02-03T00:27:41+00:00",
            "created_at": "2015-02-03T00:27:41+00:00",
            "updated_at": "2016-08-21T13:26:52+00:00",
            "featured_image": "...",
            "embed_code": "",
            "description": "...",
            "type": "Books",
            "languages": [
                {
                  "id": 1,
                  "name": "English"
                }
            ],
            "subtitles": [],
            "tags": [
                {
                  "id": 1,
                  "tag": "Approach Guides"
                },
                {
                  "id": 2,
                  "tag": "Arts"
                }
            ],
            "destinations": [
                {
                  "id": 122,
                  "name": "Turkey",
                  "label": "Middle East > Turkey"
                },
                {
                  "id": 124,
                  "name": "Istanbul",
                  "label": "Middle East > Turkey > Istanbul"
                }
            ]
        }
    ]
}

Content Types

This endpoint returns all content types.

Response data

Example response

{
  "meta": {
    "paginated": true,
    "count": 11,
    "current_page": 1,
    "has_more_pages": false,
    "last_page": 1,
    "next_page_url": null,
    "per_page": 15,
    "prev_page_url": null,
    "total": 11
  },
  "items": [
    {
      "id": 1,
      "name": "Books",
      "description": "Books & eBooks",
      "image": "https:\/\/cdn.approachguides.com\/1\/tripreads-icon-category-books.jpg",
      "weight": 9,
      "created_at": "2016-08-19T17:00:28+00:00",
      "updated_at": "2016-08-28T09:24:49+00:00"
    },
    {
      "id": 2,
      "name": "Articles",
      "description": "Articles & Academic Papers",
      "image": "https:\/\/cdn.approachguides.com\/2\/tripreads-icon-category-articles.jpg",
      "weight": 10,
      "created_at": "2016-08-19T17:00:28+00:00",
      "updated_at": "2016-08-28T09:24:49+00:00"
    },
    {
      "id": 3,
      "name": "Online",
      "description": "Online Sources & Blogs",
      "image": "https:\/\/cdn.approachguides.com\/3\/tripreads-icon-category-online.jpg",
      "weight": 5,
      "created_at": "2016-08-19T17:00:28+00:00",
      "updated_at": "2016-08-28T09:24:49+00:00"
    },
    {
      "id": 4,
      "name": "Audio",
      "description": "Podcasts & Music Playlists",
      "image": "https:\/\/cdn.approachguides.com\/4\/tripreads-icon-category-audio.jpg",
      "weight": 10,
      "created_at": "2016-08-19T17:00:28+00:00",
      "updated_at": "2016-08-28T09:24:49+00:00"
    },
    {
      "id": 5,
      "name": "Kids",
      "description": "Just for Kids",
      "image": "https:\/\/cdn.approachguides.com\/5\/tripreads-icon-category-kids.jpg",
      "weight": 1,
      "created_at": "2016-08-19T17:00:28+00:00",
      "updated_at": "2016-08-28T09:24:49+00:00"
    },
    {
      "id": 6,
      "name": "Follow",
      "description": "Who to Follow",
      "image": "https:\/\/cdn.approachguides.com\/6\/tripreads-icon-category-follow.jpg",
      "weight": 3,
      "created_at": "2016-08-19T17:00:28+00:00",
      "updated_at": "2016-08-28T09:24:49+00:00"
    },
    {
      "id": 7,
      "name": "Map",
      "description": "Get Your Bearings",
      "image": null,
      "weight": 0,
      "created_at": "2016-08-19T17:00:28+00:00",
      "updated_at": "2016-08-19T17:00:28+00:00"
    },
    {
      "id": 8,
      "name": "Videos",
      "description": "Videos that Set the Stage",
      "image": "https:\/\/cdn.approachguides.com\/7\/tripreads-icon-category-film.jpg",
      "weight": 10,
      "created_at": "2016-08-19T17:00:28+00:00",
      "updated_at": "2016-08-28T09:24:49+00:00"
    },
    {
      "id": 9,
      "name": "Experiences",
      "description": "On-Location Experiences",
      "image": "https:\/\/cdn.approachguides.com\/8\/tripreads-icon-category-recommended.jpg",
      "weight": 1,
      "created_at": "2016-08-19T17:00:28+00:00",
      "updated_at": "2016-08-28T09:24:49+00:00"
    },
    {
      "id": 10,
      "name": "Films",
      "description": "Quintessential Cinema",
      "image": "https:\/\/cdn.approachguides.com\/9\/tripreads-icon-category-film.jpg",
      "weight": 5,
      "created_at": "2016-08-19T17:00:28+00:00",
      "updated_at": "2016-08-28T09:24:49+00:00"
    },
    {
      "id": 11,
      "name": "Apps",
      "description": "Mobile Applications",
      "image": "https:\/\/cdn.approachguides.com\/10\/tripreads-icon-category-app.jpg",
      "weight": 7,
      "created_at": "2016-08-19T17:00:28+00:00",
      "updated_at": "2016-08-28T09:24:49+00:00"
    }
  ]
}

Collections

This endpoint returns all collections.

Response data

Example response

{
  "meta": {
    "paginated": true,
    "count": 1,
    "current_page": 1,
    "has_more_pages": false,
    "last_page": 1,
    "next_page_url": null,
    "per_page": 15,
    "prev_page_url": null,
    "total": 1
  },
  "items": [
    {
      "id": 10,
      "alt_id": "urOXY9aR",
      "user_id": 1,
      "folder_id": null,
      "type": "partner",
      "name": "Les Espanol",
      "code": "",
      "content_count": 5,
      "landing_page_url": "https:\/\/explore.approachguides.com\/collections\/123\/2298\/DNWaLw7o",
      "created_at": "2016-08-29T10:47:32+00:00",
      "updated_at": "2017-01-18T09:46:34+00:00"
    }
  ]
}