Guides and Sample Code

Developer

Apple News API Reference

On This Page

About the Apple News API

The Apple News API is a REST API that allows you to publish articles on iOS devices. You can also retrieve, update, and delete articles you’ve already published, and get basic information about your channel and sections.

The Apple News API has typical RESTful characteristics:

  • Has a set of resources; for example, channels and articles

  • Provides stateless create, read, update, delete (CRUD) operations on resources

  • Uses JSON (application/json) for input and output

Prerequisites

In order to use the Apple News API, you need to sign up as a publisher and set up an Apple News Format channel. For more information, see Add or share a channel in the News Publisher Help.

Content you deliver with the Apple News API must be in Apple News Format. For more information, see the Apple News Format Reference.

Host URL

All News API requests should be issued against the URL https://news-api.apple.com.

Command Line Interface (CLI)

A CLI (Ruby Gem) is available. You can also write your own code to use the API.

About Enclosing Strings in Quotes and Escaping ASCII Characters

When using command line utilities to pass strings to the API client, you should use single-quotes to enclose the string to treat the text literally. When you enclose a string in double-quotes, you will have to escape certain ASCII characters (for example, the $ character).

Failed Example using double-quotes:

alert-body="Big Company is acquiring Smaller Company for $2.5 billion."

Result:

"alertBody": "Big Company is acquiring Smaller Company for .5 billion."

Successful Example using double-quotes with an escape character:

alert-body="Big Company is acquiring Smaller Company for \$2.5 billion."

Result:

"alertBody": "Big Company is acquiring Smaller Company for $2.5 billion."

Successful Example using single-quotes:

alert-body='Big Company is acquiring Smaller Company for $2.5 billion.'

Result:

"alertBody": "Big Company is acquiring Smaller Company for $2.5 billion."

Endpoints

Apple News API has the following endpoints:

Field Types

The API uses the following standard field types:

  • UUID: A 128-bit value

  • String: JSON string

  • Boolean: JSON Boolean

  • Object: JSON object

  • Array: JSON array

  • DateTime: Date and time, represented as a string in ISO 8601 GMT (Zulu time) format

  • URL: A URL represented as a string

Common Fields Returned

These common fields are returned under the top-level data object, along with resource-specific fields.

Field

Type

Description

id

UUID

The unique identifier of the specified resource.

type

String

The type of resource (such as a channel or an article).

createdAt

DateTime

The date and time this resource was created.

modifiedAt

DateTime

The date and time this resource was last modified.

links

Object

Related URLs for this resource. See Common Links Returned and the Links Returned section in the description of each endpoint.

Common Links Returned

Links are URLs to related objects, and are returned under the data.links object. These common links are returned with every resource.

Field

Type

Description

self

URL

The URL at which this resource can be read, updated, and deleted.