Glossary

Glossary

A

AASA

apple-app-site-association file. Reference

Access-control List

Reference

Access Point

Models the connection between a location and an external physical road or external pedestrian network.

• DRIVING models a parking facility, lot, and drop-off zone where users may be safely and legally dropped off.
• WALKING models a physical entrance to a location or the nearest entrance when it's an enclosed location.

Access Token

Opaque string used to identify a client making API calls. Access tokens are generated in compliance with RFC 7519

Access Token Scope

Reference

Accolade

"Industry" recognized achievement or award that is bestowed upon a location.

Active Certificate

PLACEHOLDER

Address

An Address describes a location using elements that store a house number, unit, street name, and administrative area information. An Address can also be used to derive a pair of x/y coordinates for display or routing purposes.

Agency

AGENCY is a organization type which is a label which usually refers to a third-party partner.

API

Reference

App Clip

App Clips are a small part of an app that you can use to do something quickly, like rent a bike, pay for parking, or order food. An App Clip is registered and associated with a location and appears on a place card.

Apple Request ID

Version 4.0-compliant UUID value that's generated to uniquely identify an API request. Reference

App Store URL

A link that navigates a user to an Apple Store app. An App Store URL has the following format:

https://apps.apple.com/<country>/app/<app–name>/id<app-ID>

AQE

API Qualification Environment is an integration environment used during third-party partner onboarding.

Asset

Text, photos, images, and logos

Authorization Code

Reference

Authorization Grant Type

Reference

Authorization Service

System which issues an access token to a client after being successfully authenticated. Reference

Authorized

Quicklink relationship type. This relationship indicates that a location owner has AUTHORIZED a partner to provide a quicklink on their behalf. The partner includes the quicklink in their own location resource. The quicklink is not added to a location owner's resource.

After the partner's location is PUBLISHED, if conflation allows the quicklink to be used on the place card, then the quicklink is also "exposed" to a location owner (and a delegated partner) in Apple Business for management purposes. A location owner's management decisions do not affect the partner's description of a location.

When the location owner is unknown in a Apple Business context, that is, the location is not claimed, then the quicklink is not "exposed" for management. In these cases, Apple Maps trusts that the partner is authorized by the entity that owns the location and that this fact can be independently verified, if necessary. (Guidance)

B

Brand

A brand is a name, term, design or symbol possessing a conceptual or physical association with a location.

Brand (Insights)

Insights reporting dimension describing a user's search behavior. Brand indicates that a user searched for a location using the a brand name.

Brand Colocation

Multiple (related) brands that physically occupy the same space.

Brand Type

Brand type is used by Apple Maps to aggregate organization brands in Apple Business. Brand type is the highest level of aggregation performed upon brands. There are three brand types:

• "Regular" (Physical)
• Umbrella
• Virtual

Bundle ID

A Bundle IDs resource represents an application's unique identifier that you can register, modify, and delete. A Bundle ID is unique per "Adam ID." Reference

C

Calculated

CALCULATED is an access points and display point source type. The type indicates that coordinates were originated via system calculation and have not been manually curated.

Caller Name Delivery (CNAM)

Reference

Call-to-Action

In place card and showcase contexts, this is a UI element displayed on a device that a user may tap to invoke an action.

Caller Authentication Provider (CAP)

A Caller Authentication Provider is a service that verifies the identity of a telephone caller to ensure they are who they claim to be, reducing fraud, spam, and spoofed calls. Providers validate caller ID information, allowing businesses to build trust with customers through authenticated calls.

A CAP may be:

• A third-party partner, or
• A capability provided directly by a carrier or network operator.

Cascade

Describes "inheritance." Per business rules, an allowable property takes the same value as the property that's held by another resource.

Category (Insights)

Insights reporting dimension describing a user's search behavior. Category indicates that a user searched for a location using a category, product or service name.

Claimed Location

A location which is claimed, or created and claimed by an OWNER which is then subsequently verified by Apple Business.

Client Identifier

Issued by Apple Business after successful registration of an OAuth app. The client identifier (client_id) is a unique public version 1.0-compliant UUID that's assigned to an app.

Client Secret

Issued by Apple Business after successful registration of an OAuth app. A client secret (client_secret) is issued once at the conclusion of the registration process and does not expire unless it is invalidated. The client secret, known only to the app and the authorization server, is used to generate an access token and make API requests on behalf of a user. It is generated using a cryptographically-secure library and is a 256-bit value that is converted to a hexadecimal representation.

Code Challenge

Base64-URL-encoded string of the SHA256 hash of the code verifier

Code Verifier

Cryptographically random string with characters A-Z, a-z, 0-9, punctuation characters -._~, and between 43 and 128 characters long. A code verifier (code_verifier) is used to derive a code challenge.

CSAM

Child Sexual Abuse Material.

Conflated Record

A Conflated Record is the merger of available Vendor Places and internal edits. A Conflated Record represents the data state of a location that is eligible for display on a device.

Coordinate Precision

Decimal degree significance

Decimal Position	Ground Measurement
1st	~11.1 kilometers
2nd	~1.1 kilometers
3rd	~110 meters
4th	~11 meters
5th	~1.1 meters
6th	~0.11 meters

Creative

These are assets used to enrich a location's place card or showcase. On a place card these may be:

• Cover photos ("hero images")
• Photos and captions
• Showcase photos and copy

CTA

Call-to-action

D

Delegation

Delegation is the assignment of authority from one organization to another to manage and maintain resources. The specifics of what can be managed/maintained is described in the delegated organization's entitlements which are further defined using permissions.

Device

Refers to any category of hardware product: iOS device, iPadOS device, iOS and iPadOS devices, Android device.

Direct (Insights)

Insights reporting dimension describing a user's search behavior. Direct indicates that a user searched for a location using the using the location's name and address.

Display Point

The curated position to use as the point-based representation of a location.

DMARC

Domain-based Message Authentication, Reporting and Conformance (DMARC). Reference

DQE

Data Qualification Environment is an integration environment used during third-party partner onboarding.

DUNS Number

Assigned to a business by Dun & Bradstreet (D&B). For more information on how to obtain a DUNS number for your business, see D&B - Choose Your Country or Region.

E

Enclosed Location

Location contained by another location. For example, a store inside a mall, airport, university campus building, and so on.

Entitlement

Describes a relationship between a delegated partner and a resource. Entitlements are further specified using permissions and roles.

ETag

Etag is a UUID version 1 label generated by Apple Business, not a partner. ETag supports three use cases. The first is to enforce concurrency so that multiple update requests cannot override each other's edits in scenarios known as "race" conditions.

For concurrency control, an ETag that is returned in a response header is compliant with RFC 7232

The second use case that the ETag value supports is versioning. When versioning (update) of a resource is supported, an Etag value is included in the response body of an API request.

The third use case is to support Get (filter) operations when a user wants to retrieve a specific version of a resource. Note that this use case is not available for all Get operations.

F

Flexible Action Link

A link that navigates a device user to an OWNER provided URL. Delivered as action links, they do not have App Store URL associations.

An App Store URL is used to retrieve and display an App provider's logo alongside a call-to-action on a device. A flexible action link will retrieve a brand asset or a default glyph.

Flexible action link may be universal links.

G

Gallery

A "staging" area used to store a collection of assets under a brand or location.

Grant Type

The grant_type parameter in an OAuth 2.0 token API request specifies the method an application uses to obtain an access token.

H

HEIC

High-Efficiency Image Container. Reference

I

Image

Reference

J

JPG/JPEG

Joint Photographic Experts Group (JPG/JPEG) raster-graphics file format.

JSON Web Token

JSON Web Token (JWT) is an "...open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object."

L

Location

A record describing an area, place or point of interest. These are physical, Apple Maps verified locations.

Location Owner

First party proprietor of a location.

M

Manually Placed

MANUALLY_PLACED is an access points and display point source type. The type indicates that coordinates were originated via a manual process or were curated after system calculation.

N

Non-primary

In the context of a list (array), a non-primary value is a value that is not listed first. Using JSONPath notation, this is a value which is not listed first in a 0-based index. In this example, the non-primary value is "dining.dessert_shop.ice_cream_shop.gelato_shop".

"categories": [ "dining.dessert_shop.ice_cream_shop", "dining.dessert_shop.ice_cream_shop.gelato_shop" ]

O

Organization

Organization is the top-most entity within Apple Business. An organization registers with Apple Business to use the portal to manage their Apple Maps information. An organization may operate in one or more countries. In each country, an organization may operate one or more brands.

Organization Type

Apple Business supports two (2) organization types:

• Owners
• Partners

In the system, these types are encoded as OWNER and AGENCY

Other

Quicklink relationship type. The relationship between the location owner and the quicklink is described as follows:

• Location owner is not the OWNER of the quicklink.
• Location owner has not AUTHORIZED a partner to provide a quicklink on their behalf.

(Guidance)

Owner

Quicklink relationship type. This relationship indicates that a location owner is the OWNER of the quicklink. In other words, the quicklink is a property of the location owner. The location owner includes the quicklink in their own location resource.

After the location is PUBLISHED, if conflation allows the quicklink to be used on the place card, then the quicklink is also "exposed" to the location owner (and a delegated partner) in Apple Business for management purposes. (Guidance)

P

Permission

An attribute of an entitlement, a permission is an explicit right to perform an action upon a resource. One or more permissions are assigned to a role.

Photograph

A photograph (also known as a photo), is "...created by light falling on a photosensitive surface, usually photographic film or an electronic image sensor..." Reference

PII

Personally identifiable information. Reference

Place Card

Place card information includes street address, a phone number, a webpage link, customer reviews, and more.

Refer to the Partner Onboarding Guide for more details.

Place Card Gallery

A scrollable collection of assets, such as photos, expected to be displayed on a place card.

Place Card URL

placeCardUrl is an apple-generated link which invokes the display of a mapped location along with its respective place card. The link is provided when a location is PUBLISHED.

PNG

Portable Network Graphics (PNG) raster-graphics file format.

Primary

In the context of a list (array), a primary value is a value that is listed first. Using JSONPath notation, this is a value which is listed first in a 0-based index. In this example, the primary value is "dining.dessert_shop.ice_cream_shop".

"categories": [ "dining.dessert_shop.ice_cream_shop", "dining.dessert_shop.ice_cream_shop.gelato_shop" ]

Proof Key for Code Exchange (PKCE)

Reference

Punch-out

A punch-out allows an Apple Maps user to tap on a photo, review, or a location description and be navigated, via a partnersResourceURL, to a website or an app.

When tapped, the client device checks if the partnersResourceURL is associated with an app that's locally installed. If installed, Apple Maps "punches out" to the app and navigates the user to the target resource. If not installed or not found, Apple Maps "punches out" to Safari and navigates the user to the target resource.

For more information, refer to Developer Documentation

R

RAP

Report a problem

Rate Limit

Rate limits are measured in queries per second.

Rich Call Data (RCD)

Rich Call Data allows a calling party to associate out-of-band rich media and metadata with a phone call, such as:

• Caller name (brand name)
• Logo
• Call reason. For example, “Customer Support”, “Delivery Update”, and so on.
• Verified identity indicators

RCD is not embedded directly into SIP headers. Instead, SIP carries a URL pointer to RCD hosted elsewhere such as a CAP.

Redirection Endpoint

The URL an authorization server redirects a user back to after successfully authorizing an application. This must match the redirect URL that was registered when creating an OAuth app. Reference

Refresh Token

Credentials used to obtain access tokens. Refresh tokens are issued by Apple Business and are used to obtain a new access token when the current access token becomes invalid or expires. Reference

A refresh token issued by Apple Business does not expire but may be invalidated when:

• Apple Business revokes the refresh token.
• User revokes third-party partner platform access to their Apple Business account.
• Apple Business changes their authentication policy.

Regular Brand

A business entity with physical locations that possess a consistent category, URL, and display name.

Examples
Starbucks Corporation, Walmart

Resource Owner

Entity capable of granting access to a protected resource. Reference

Response Type

The authorization endpoint is used by the authorization code grant type and implicit grant type flows. The OAuth app informs the authorization server of the desired grant type using the response_type parameter. response_type must be code for requesting an authorization code and token for requesting an access token (implicit grant). Reference

Role

A named, assignable collection of permissions

S

Scope

scope refers to the specific permissions and level of access granted to a client application or an API token.

Sensitive Field

A data field which, when edited by a location owner, is subject to review by Apple Map. Sensitive fields are:

• Categories
• Display Names
• Main Address

Shadow Brand

When an organization does not create a brand, Apple Business will systematically generate a brand on their behalf. Sometimes referred to as a "shadow" brand, the existence and purpose of the brand may not be obvious to the organization.

The outcome of a successful delegation process is the generation of an associative "link" between a delegated partner and an organization. The brand entity serves as a mechanism to link the respective parties.

The brand entity will exist even if the resource has not been explicitly created by a user to manage brand-related assets.

Session Initiation Protocol (SIP)

For telephony, SIP is responsible for:

• Call setup (INVITE)
• Ringing (180 Ringing)
• Answer (200 OK)
• Teardown (BYE)
• Transporting call-related metadata via headers. For example, caller identity, RCD URLs, and so on.

Reference

Service Account

A non-human account used to run automated services and execute applications such as Apple Business API.

Severity

Severities are used to categorize validation results. Possible values: VIOLATION, WARNING INFO

Similar Location Metrics

Insights reporting metrics which can be identified by the SIMILAR_ prefix. For example:

SIMILAR_SEARCH_LOCATION_TAP

SMB (Small & Medium Businesses)

These are businesses with fewer than 25 physical locations.

Spatial Metrics

Insights reporting metrics which can be identified by the SPATIAL_ prefix. For example:

SPATIAL_DIRECTION_LOCATION_TAP

Special Character

Symbol used in writing that represents something other than a letter or number.

State (OAuth)

An opaque value used by the client to maintain state between the request and callback. Reference. State is used to mitigate CSRF attacks by using a unique, randomized string to accompany an authorization code flow.

Sub-brand

Brand that has a parent or "umbrella" brand. For example, IHG Hotels & Resorts is an umbrella brand with sub-brands such as InterContinental Hotels & Resorts, Holiday Inn, and so on.

SVG

Scalable Vector Graphics (SVG) vector image file format.

T

Third-party Partner

A company whose core services are the management of locations on behalf of clients that are not enrolled in Apple Business or companies which are enrolled. These companies include marketing automation software companies, analytics platforms, and data aggregators.

Token Type

Indicates the kind of access token issued (for example, Bearer).

U

Umbrella Brand

A head or parent brand possessing one or more sub-brands. For example, IHG Hotels & Resorts, Marriott International, Yum! Brands, and so on.

V

Vendor Place

A partner location record whose processing is completed. A Vendor Place possesses the required data condition making it eligible for consideration by the Conflation Process.

Virtual Brand

A virtual business entity or a collection of related business entities that have a consistent category, URL, and display name.

Characteristics	Examples
No physical presence	Amazon.com, Inc., Etsy, Inc.
Business conducted via the web or mobile apps	Uber Technologies, Inc.