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 firstname.lastname@example.org for domain whitelisting.
The API is accessed by making http GET requests to a specific endpoint URL.
The base HTTP endpoint for the latest version is:
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.
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.
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.
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.
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.
If multiple fields need to be expanded on the same Resource, they can be separated by a comma.
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.
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:
In fact, by default, this query will return the results for the following query:
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.
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:
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:
To access the latest articles from Turkey, the endpoint is as follows:
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:
Each vocabulary is keyed off an id field. Let’s use “expand” and “fields” to return the name of each vocabulary:
The important vocabularies are as follows:
3 — Categories
11 — Series
To access the Countries vocabulary endpoint:
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.
For example, the following query will look up an article’s endpoint:
It will return the “items” field which can be used to make a new query or expanded.