GlobalPost v1 API Documentation

Note To Reader: This document is a introduction to the GlobalPost API. While not comprehensive, it will cover the primary functionality and abilities available to developers. It’s recommended that you read this document sequentially – otherwise concepts may be confusing as portions of this guide will reference previously detailed sections.

The GlobalPost API is a read-only JSON API, which allows developers the ability to access the full catalogue of GlobalPost articles and their associated media. Available data includes headlines, bylines, full article content, and more.

The GlobalPost API is currently only available on the globalpost.com domain. To request API access, please contact ndynan@globalpost.com for domain whitelisting.


Endpoints

The API is accessed by making http GET requests to a specific endpoint URL.

The base HTTP endpoint for the latest version is:

http://www.globalpost.com/api/v1

Resources and Resource types

A Resource is any endpoint in the API.

The API is descriptive. Every URL in the API will return a Resource and every Resource will have at least two fields defined, an href and resourceType.

Property: Href

The href property acts as the URI of the Resource and acts as its unique identifier. It is equivalent to the url needed to request it. The href will contain any query string data used to request that Resource.

Property: ResourceType

There are 3 primary resource types:

  • Item — Represents a thing — such as an article — that holds data fields.
  • Collection — A collection is an array of pointers to a specific grouping of items. This could be a taxonomy term, a content type, or a search query. Collections will contain pagination fields.
  • Index — Is like a sign post, which point toward other destinations within the API. These other destinations can be other indexes or collections.

Exploring the API

On a Resource, some fields can be simple resource objects with their own href and resourceType properties. They can act as references to other Resources.

For Example, the Base URL will return an Resource object with a property called content, which is a simple Resource object. Content related data can be found using the href field of that Resource.

This architecture holds true throughout the API and can be used to dig through various layers of the API.


Expanding Reference Fields

Sometimes when a Resource is requested it doesn’t contain all the data you expect. Data may belong to another resource that is only being pointed to via the requested Resource’s reference field.

For example, this is the case with the photo field on an article Resource Item. The photo field is a simple resource object with an href to the Resource’s endpoint.

http://www.globalpost.com/api/v1/content/articles/[item-id]

The photo field just contains a pointer to the photo item Resource

In this situation, a request can be “expanded” in order to return the data of the resource.

http://www.globalpost.com/api/v1/content/articles/[item-id]?expand=photo
The photo field now returns the author, caption, change date, copyright, created date, href, and id.

In the case of the photo Resource, multiple Resources need to be expanded to get to the photo’s URL.

Dot syntax is used to expand Resource references deep within the Resource reference tree.

http://www.globalpost.com/api/v1/content/articles/[item-id]?expand=photo.image

If multiple fields need to be expanded on the same Resource, they can be separated by a comma.

http://www.globalpost.com/api/v1/content/articles/[item-id]?expand=photo.image,author.bio

Limiting Reference Fields

Sometime it is beneficial to reduce the number of fields returned from the API for ease of use. A request can be limited using the “fields” parameter by listing desired fields using the previously covered dot and comma notation.

In the example below, a request is expanded on the photo and taxonomy field.

This will return a Resource with more photo and taxonomy data, as previously outlined. However, the final request will only contain the fields listed after “&fields=”

First the headline and subhead are requested from the original Resource. Then the photo photo.image.styles.globalpostFirebird is returned, limiting the photo.image.styles field. Additionally taxonomy.primary.name is returned, limiting the taxonomy.primary field.

http://www.globalpost.com/api/v1/content/articles/[item-id]?expand=photo.image.styles,taxonomy.primary&fields=headline,subhead,photo.image.styles.globalpostFirebird,taxonomy.primary.name
Only the taxonomy field name is returned on the taxonomy Resource

Note: Using the “fields” parameter do es not increase the API query speed, it does however provide a simpler Resource object with which to work with and allow a smaller payload.


Finding Recent Articles

The GlobalPost API provides a simple way to access a list of the most recent article endpoints:

http://www.globalpost.com/api/v1/content/articles

In fact, by default, this query will return the results for the following query:

http://www.globalpost.com/api/v1/content/articles?limit=50

The use of the “limit” parameter will return the 50 most recently published articles.

Additional article Resources can be retrieved by adjusting the “limit” query parameter, while the “offset” parameter can be used to offset the number of articles retrieved. Make sure to chain these parameters with the “&” symbol.

For example, this query will return 50 articles, skipping the 50 most recent articles.

http://www.globalpost.com/api/v1/content/articles?offset=50&limit=50

Every articles Resource will return “previous”, “next” and “last” fields, which will provide URLs to help build requests and provide a mechanism for easy pagination.


Finding Media By Taxonomy

Resources such as articles, videos, and photos are categorized with a number of Taxonomy terms. Therefore, these resources can be accessed via their associated Taxonomy terms.

The taxonomy term endpoint is as follows:

http://www.globalpost.com/api/v1/taxonomy/terms

This endpoint is paginated and will return the 50 most recent terms.

Terms are identified by a taxonomy id.

For example, the following endpoint is the Turkey term:

http://www.globalpost.com/api/v1/taxonomy/terms/81

To access the latest articles from Turkey, the endpoint is as follows:

http://www.globalpost.com/api/v1/taxonomy/terms/81/content/articles

Terms can be paginated through the “previous”, “next” and “last” fields as well as the “offset” and “limit” query strings.

Finding Terms with Vocabularies

Taxonomy terms are also categorized into “vocabularies.” The vocabularies endpoint is located here:

http://www.globalpost.com/api/v1/taxonomy/vocabularies

Each vocabulary is keyed off an id field. Let’s use “expand” and “fields” to return the name of each vocabulary:

http://www.globalpost.com/api/v1/taxonomy/vocabularies?expand=items&fields=items.name

The important vocabularies are as follows:

3 — Categories

6— Countries

9— Regions

11 — Series

14— Trending

To access the Countries vocabulary endpoint:

http://www.globalpost.com/api/v1/taxonomy/vocabularies/6/terms

This endpoint will return country terms endpoints which than can be used to access media Resources as detailed above.


Search by URL Alias

A basic search is available within the API. It works by using a URLs alias to lookup an associated API Resource.

http://www.globalpost.com/api/v1/content/search?alias=[url-alias]

For example, the following query will look up an article’s endpoint:

http://www.globalpost.com/api/v1/content/search?alias=article/6575081/2015/06/08/forget-iran-israeli-government-has-found-another-existential-threat-worry

It will return the “items” field which can be used to make a new query or expanded.

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.