Skip to main content

Frequently Asked Questions

Apple Business API​

What are the base URLs for Apple Business API?

EnvironmentPath {url}
AIEhttps://api-qualification.business.apple.com
DQEhttps://data-qualification.business.apple.com
Productionhttps://business.apple.com

Authentication & Authorization​

Access Token​

If I request a new access token before the current one expires, will that invalidate the current access token?

No, an existing token is not invalidated. We recommend that you only generate a new access token close to the time when the current access token is expected to expire.


My organization manages locations directly, and is also delegated by other organizations to manage locations on their behalf under their brands. Can the same access token be used to call web services for ourselves and on their behalf?

Yes.

Aggregate Ratings & Reviews​

Aggregate Ratings​

Must we create an aggregate rating before creating a review?

No. However, in order to display a review on client devices, you must create an aggregate rating. You may create only an aggregate rating without reviews. The aggregate rating may be displayed on client devices in these circumstances.


Do you expect the aggregate rating to reflect only the reviews we've submitted or the superset of all reviews, some of which we have not submitted due to their excessive count?

The aggregate rating should be derived from the entire collection you maintain in your database.


Must an aggregate rating have a corresponding relationship to all reviews we've submitted? For example, must our count of reviews equal the count of reviews we've submitted to you?

No.


When an author only provides a rating, not a review, how do you want us to handle that information?

Update starRatings in the aggregate rating resource.


Is access to these API restricted? Can a brand owner submit their own reviews?

Location owners cannot use these API.

Pricing​

Pricing in the Business Listings Specification includes range, currency code, minimum, maximum, and average pricing. Why aren't they supported in API?

Only a limited number of partners provided range data with currency code, minimum, and maximum pricing. We're postponing the introduction of these concepts until we better understand what data is actually available and the obstacles that may exist to obtaining it from a broader set of partners.

Star Ratings​

Why is the data type for starRatings an array if we can only add one category?

The single listed value you provide is expected to be "overall" in scope. In the future, we may allow a location to possess more than one value to describe other overall assessments like "cleanliness," "eco-friendliness," "staff & service," and so on.

This is also the reason why starRatings in a review resource is an array. Currently, validations only allow for the a single value. In the future, we can couple any planned enhancements of aggregate ratings with enhancements to starRatings in a review.


We had previously provided aggregate ratings and reviews in bulk. Some keys used in bulk are present in API but are differently labeled. Can you elaborate on why some keys were changed?

We wanted to align with available de facto standards as much as possible to facilitate knowledge transfer. Here are some keys and their external references for consultation.

ResourcePropertyReference
Aggregate RatingstarRatings.categoryModeled on Schema.org
Aggregate RatingstarRatings.bestRatingSchema.org
Aggregate RatingstarRatings.worstRatingSchema.org
Aggregate RatingstarRatings.ratingValueSchema.org
Aggregate RatingstarRatings.ratingCountSchema.org
Aggregate RatingstarRatings.reviewCountSchema.org
Reviewreview.nameSchema.org
Reviewreview.reviewBodySchema.org
Reviewreview.author.givenNameSchema.org
Reviewreview.author.alternateNameSchema.org
Reviewreview.starRatings[].ratingValueSchema.org
ReviewinteractionStatisticsModeled on Schema.org
Reviewreview.interactionStatistics[].interactionTypeSchema.org
Reviewreview.interactionStatistics[].[interactionType='HELPFUL']Modeled on Schema.org
Reviewreview.interactionStatistics[].userInteractionCountSchema.org

Reviews​

Do you expect all reviews about a location to be submitted? Some of our locations have thousands of reviews.

There is no "hard" upper limit on the count of reviews you may submit. However, if you wish to set an upper limit, 200 of the most recent reviews is recommended.


What is the purpose of the partnersReviewId?

When a user interacts with a rating or a review on a client device, the Apple Maps app uses a Map Action URL to "punch out" to a software provider's application or a web browser. The partnersReviewId is used to identify the specific resource such as a review, rating or photo that a user should be navigated to.

Review API allows update of the partnersReviewId, but partners are generally advised not to unless it is necessary. When updating the partnersReviewId, partners should be cognizant that such changes may "break" any of their expected behaviors.

Refer to this Developer Forums thread for public details about Map Action URLs. Subscribers to Apple Business Register may access full details about Map Action URLs here.

note

Map Action URL data is not delivered to Apple via API


Why do you ask for scale? We already provide our rating system's bestRating in the Aggregate Rating. Why can't you internally derive it?

You're not required to create the aggregate rating first. To avoid a dependency upon aggregate ratings to know your rating system's upper and lower range, we only need your best rating passed into scale. This allows us to process the review without delay. However, in order to display a review on client devices, an aggregate rating must exist.


Why is starRatings an array?

Initially, we only expect a single ratingValue. In the future, we may support types of rating such as "cleanliness," "eco-friendliness," "staff & service," and so on.


We had previously provided a reviewer's profile picture in bulk. In that process, we submitted photo size information (thumbnail thru xxlarge, pixel height and width). Your review API don't require this information. Why?

In our new process, we download your image using the url you provide. We validate for expected minimum dimensions, aspect ratio and other desired qualities. We then store the image and derive from that image the sizes we need for our client devices. Because we are validating the actual dimensions of an image after we download it, there is no value in asking you in advance for those dimensions.

Instead, the data specification will provide guidance on minimum and maximum photo sizes and aspect ratios. If your image fails offline validations, we'll report these issues to you using our Feedback API.


In bulk, review type was supported but is not supported in API. Why?

Historically, the data was not being delivered so it was not included in our API design.


In bulk, user profile_name was required but is not supported in API. Why?

Not all partners delivered profile_name even though it's a required field. Some partners only provided first_name. To simplify, we made givenName mandatory. If you had been providing profile_name, then you may use alternateName.


Using bulk terminology to facilitate "re-mapping" of user information, what do you want us to pass into givenName

Bulk keys and corresponding API fields

profile_namefirst_namelast_initialGuidance
✓xx--> givenName
✓✓xprofile_name --> alternateName;first_name --> givenName
x✓xfirst_name --> givenName
x✓✓first_name --> givenName; last_initial --> lastInitial

If a location asset, which "traces" back to a reviewer's image in our system, is rejected, what happens to the review?

The review is unaffected.

Critic & Critic Summary Types​

It is our business practice to publish individual reviews and accompany them with a written digest (a summation or condensation of a body of information). Conceptually, our summations correspond to your CRITIC_SUMMARY review type. Do you expect only a CRITIC_SUMMARY review? Both? Or, just CRITIC reviews?

You should provide a CRITIC_SUMMARY review type. You may provide CRITIC review types. We will accept both.


When creating a CRITIC review type, the synchronous response includes VALIDATION__WorstRatingIsPresent in the validation reports. Are you expecting us to take any action?

If your plan to deliver one (1) CRITIC review type per location, then you can ignore the report.

HTTP Status Codes​

What is the system response when we attempt to retrieve (GET) an aggregate rating resource but we had failed to created one first?

404 Not Found


What is the response when we attempt to update (PUT) an aggregate rating resource but we had failed to created one first?

404 Not Found

Worst Rating​

What was the reason for enhancing the review API to support worstRating?

A partner that only plans to deliver one (1) CRITIC or CRITIC_SUMMARY review type per location should not have to integrate with the aggregate rating API in order to indicate a worstRating value that isn't 0. We are sensitive to a partner's need to keep integration costs to a minimum. This enhancement attempts to address that.

Apple Overrides​

Contest​

Must we create an aggregate rating before creating a review?

Can we update other location attributes when accepting an Apple override?

Yes.


How long does a contest review take to complete?

Completion within 3 business days is targeted. Note: Location remains in PROCESSING state until the review is completed.


Is there a maximum number of times that we can contest an Apple Override?

You may contest an Apple Maps override of a display name twice. This limitation only applies to a display name.


We currently do not support webhooks. What query do you recommend we use to fetch notifications or feedback about Apple overrides?

We recommend that you periodically request feedback. Add additional parameters such as date and pagination limits to suit your operational requirements.

GET {url}/{version}/orgs/{orgId}/feedback?ql=resourceType==LOCATION;type==MAPS_DISPLAY

What happens to an Apple override when each location update we make excludes a value that matches the override feedback?

The Apple override "moves" to the latest (ETag) version. After each successful update, you can expect a new notification, feedback, and webhook event message about the Apple override.


What happens if we update a location to match the Apple override value but then we make another update that reverts the property back to what had led to the Apple override in the first place?

We will monitor for these kinds of changes.


When feedback lists multiple Apple overrides codes for the same location (ETag) version, will each appleOverrideId be distinct?

Yes.


How will we know when we can and cannot contest information appearing on a place card?

Contestable information appears in MAPS_DISPLAY feedback with an APPLE_OVERRIDE__. It is only when this code is provided to you that you can contest information appearing on a place card.

Brand​

Can a brand be associated with more than one brand asset possessing the same intent?

Only a single brand asset under the brand may possess a particular intent. A brand asset with an intent serves a singular purpose with respect to all the locations associated with the brand. For example, if the intent of two brand assets was the same, say PLACECARD_LOGO, given that a place card can only show a single logo, our system would not know which one to choose.


I have a new logo for my locations. What happens when I create another brand asset with the same intent?

If you choose to not delete the existing resource, when you create a brand asset with an intent of PLACECARD_LOGO, we will replace the existing resource with the new one.


Can we create brands in Apple Business to manage our listings?

Yes. However, your ability to create locations from your listings and immediately associate those locations with brands depends upon whether you are delegated or not. Considerations:

  • If you manage listings on behalf of an entity that has intellectual rights to the brand, and that entity is not represented as an organization in Apple Business, then you can create the brand and immediately associate locations with the brand. The brand you create does not require approval by Apple Business.
  • If the entity you're managing listings on behalf of is an organization in Apple Business, then your organization should be delegated by that organization. The organization must already have an approved brand before it may delegate you to manage that brand and its associated resources.
  • If you don't manage listings on behalf of the entity that has intellectual rights to the brand, but want to use a brand to help organize your listings, then you may create the brand and immediately associate locations with it.

Can I create a brand and immediately associate locations with the brand?

No. The brand must first be approved. It may take up to three (3) days to process approval of the brand. Once approved, you can begin to associate locations with the brand.


Are brand assets subject to the same approval process as the brand? Also, is the status of the brand affected by the outcome of the brand asset's approval process?

Brand assets are subject to review because of their potential use on a device. The brand asset review process and its outcome does not influence the status of the brand the assets are associated with.

If you're not delegated, brand assets are not expected. Without express permission, via delegation, we have no rights to use trademarked materials.


We have acquired a competitor which also happens to be an organization in Apple Business. How do we transfer the resources of the acquired company to be under our organization?

You cannot. You'll have to create a new brand and re-create all applicable resources. External to Apple Business, we recommend that you obtain all the original data used to create the resources. Then:

  • Create a new brand, create brand asset(s) and submit for approval
  • After approval, create locations and reference the newly created brand's identifier

You may re-use the same partner-generated identifiers (e.g., partnersLocationId) associated with resources of the acquired company or create new identifiers.


We're a brand enterprise, do we need to create a brand before we can add locations?

Yes.


We're not delegated, do we need to create a brand before we can add locations?

As a non-delegated partner, you may manage locations under the organization, under a brand or both. A brand may be used to conveniently manage locations possessing a conceptual relationship.


What is the maximum number of brands that can be created?

The answer depends upon your organization type.

Organization TypeMaximum
Owner (Organization brand and location owner)1,000
Agency (Undelegated Partner)10,000

Brand API​

What happens to locations when the brand they reference is deleted?

Apple Business will delete the locations. You may undelete locations but their resource states change to REJECTED because they reference a deleted brand. Organizations that own their locations are required to update brandId references in these locations. Third-party partners (not delegated) may update the brandId or remove their values.

Brand Asset​

Can the same brand asset be shared across multiple brands?

No.


Can the same image be shared by a brand asset and a location under the same brand?

Yes. Brand asset and location assets may reference the same image provided the image satisfies the respective resource's data requirements. More broadly, the same image can be referenced among all resources which support the capability.


Can we update a brand asset's imageId to a different image?

You may update the brand asset's imageId using:

  • An entirely new imageId you've received from the media API
  • imageId associated with a "soft" deleted brand asset

Under what circumstances might you reject a request to create or update a brand asset which references an image?

If the image's resource state is REJECTED, the brand asset cannot be created/updated.

When an image is IN_REVIEW or SUBMITTED, provided there are no other exceptions, we shall create/update the brand asset. Our general recommendation is that you wait until the image is APPROVED.


What is the purpose of AltTextsTextIsUnchanged in a validation report?

We cannot assume that when you replace a brand asset's image with another, the current and prior images are exactly alike. This validation serves to remind you that altTexts exists and, if the image is different from the prior version, you may want to update altTexts.


We've been delegated to manage an organization's locations. They've informed us that client devices are not displaying a cover photo on their place card. We have no feedback to suggest there's any problem with the cover photo we've submitted.

Check that you've successfully created a logo using the brand asset API. Or, that your customer has successfully completed this task using the Apple Business portal. Both logo and cover photo must be present.

Brand Asset API​

What happens after a brand asset is created?

The brand asset is eligible for association with all locations associated with the same brand.


What happens to email IDs when the brand asset they use is deleted?

Each email ID's resource state is changed to DEACTIVATED. A response to an attempt to create or update an email ID resource in this state will return 400 Bad Request.

Caller ID​

Do you generate notifications and feedback describing events related to BCID resources?

Yes. Notifications and feedback will refer to a BUSINESS_CALLER_ID resource type when describing events.

How does the iPhone use Rich Call Data (RCD) to present an incoming call, and what fallback behavior applies when RCD is unavailable or untrusted?

High-level call flow:

  1. Incoming SIP INVITE arrives at the carrier/device
  2. iPhone OS inspects SIP headers
  3. If an RCD URL is present and trusted:
  • The iPhone fetches the URL over HTTPS
  • The returned data is validated (origin, signature, policy)
  1. iPhone UI is rendered:
  • Brand name
  • Logo
  • Call reason/department (if available)
  • Trust indicator

Fallback behavior: If no RCD URL is present, URL fails to resolve, or the data is untrusted/policy-blocked, then the iPhone falls back to:

  • Carrier-provided CNAM
  • Partner-provided brand defaults
  • Or, generic number display

How do we move a phone number from one brand to another?

You must first delete the phone number then create a new BCID resource under a different brand. See Move BCID Resource for more details.

Since a brand and brand asset must be PUBLISHED before we can create or update a caller ID resource, what happens if a user deletes a brand or brand asset?

All the brand's caller ID resources will be DEACTIVATED.

Some Contact Center as a Service (CCaaS) platforms historically reused outbound calling numbers across multiple customer organizations to reduce provisioning and operational costs. However, this model conflicts with modern caller authentication, branding, and reputation requirements, and is increasingly being replaced by tenant- or brand-scoped numbering. How does BCID handle the former?

  • A Partner may only assert brand identity for phone numbers that are explicitly associated with a delegated brand.
  • If a phone number is used across multiple brands or organizations, it cannot be unambiguously scoped to a single delegation.

In CCaaS environments where:

  • Outbound numbers are shared across multiple SMB customers, or
  • Numbers are platform-owned rather than tenant-owned.

The Partner cannot safely or correctly:

  • Bind the number to a single delegated brand.
  • Publish RCD, or
  • Assert branded caller identity.

The iPhone is already showing branded calling. What differentiates BCID from what's currently displayed on client devices?

While some devices may already display limited caller branding, that information is typically derived from carrier defaults or third-party data sources and is not directly managed by the business.

Apple Business’s BCID enables businesses to centrally manage and control their brand identity across the Apple ecosystem. In addition, BCID allows businesses to specify the purpose or reason for each call, enabling that context to be displayed on supported devices at call time.

What department/reason categories do you provide for phone numbers?

Refer to department categories.

What is the maximum number of BCID resources that can be created?

150,000 BCID resources are supported per brand. This limit is configurable. Reach out to Apple Business support to request a different limit.

Which brand-related notifications should we monitor?

When an organization delegates a brand to you for the first time, a DELEGATION notification type is generated and an email is sent to an administrator within your organization.

You should:

  • Fetch all delegated brands and their associated assets to view details such as resource state and approval state.
  • Continuously monitor DELEGATION notifications to detect new delegations and the revocation of existing delegations.

When an Owner updates a Brand, the system generates a notification as the Brand resource transitions state. A delegated partner should review these notifications to determine whether hosted RCD or fallback data requires adjustment to remain consistent with the system of record.

Partners are recommended to closely monitor changes directly affecting the BCID experience which may conflict with hosted RCD. Changes include:

  • Brand asset logo
  • Brand display name
  • BCID resource call reason/department
Notification TypeResource State / TransitionPartner Guidance
MAPS_DISPLAYSUBMITTEDReview the updated Brand details and assess potential impact to hosted RCD or fallback brand data. No immediate action may be required prior to approval.
PROCESSING_FAILUREFAILEDThe Brand update has failed. Monitor for subsequent re-try.
PROCESSING_SUCCESSFULPUBLISHEDThe Brand update has been approved by Apple Business. Assess potential impact to hosted RCD or fallback brand data as needed to reflect the approved Brand details.
VALIDATION_FAILURESUBMITTED → REJECTEDThe Brand update was not approved or there are validation exceptions. Continue using the previously published Brand details. Monitor for subsequent re-submission.
note

A DELEGATION notification indicating changes in resource and delegation state is not re-generated.

Claimed Locations​

What happens to location data we provide when the same location is claimed in Apple Business (Portal) by one of our franchise owners/operators? Specifically, whose location data takes precedence?

The following information submitted by a user on behalf of a claimed location will ordinarily take precedence over what you may provide:

Delete API​

When I delete a resource is it physically deleted?

Not immediately. Brand, location, and location assets are held for a short period and then physically deleted.


Why do you pass an etag value in a response header after a delete request?

Where not explicitly stated, a delete request results in a "soft" deletion of the resource. Whenever this is the case, an etag value is returned. If, in the future, we support "Undelete" services, possession of the etag value would be important.

ETag​

Is a new etag generated for a resource each time a new notification/feedback type is generated?

No. A new etag is only generated when you make a change to the resource. When you call the Feedback API without an etag as a query parameter, the response is expected to include all feedback types that were generated for the latest (ETag) version of the resource.


Is it recommended to store the etag, or should we call GET to fetch the latest etag before every PUT?

Fetching the latest etag immediately before PUT can bypass optimistic concurrency protections. The etag should represent the version you originally read. If another user modifies the resource, your update should fail with 412 Precondition Failed, prompting reconciliation rather than silent overwrite.

You should store the etag on your side. By storing the etag:

  • You eliminate an unnecessary network call.
  • You reduce read load on the API.
  • You avoid race conditions introduced by fetching a newer version immediately before updating.
  • You preserve true optimistic concurrency semantics.

How do we find out the latest version of a resource? We're getting an INCORRECT_ETAG response when attempting to make an update.

Use a Get by ID service. The latest etag will be included in both the response header and the body.

Insights API​

Similar Location metrics are limited to certain countries. What are they?

Currently, these country codes are supported:

AE,AR,AT,AU,BE,BR,CA,CH,CL,CZ,DE,DK,ES,FI,FR,GB,GR,HK,HU,ID,IE,IN,IT,JP,MX,MY,NL,NO,NZ,PH,PL,PT,SA,SE,SG,TH,TR,TW,US,VN,ZA

JSON Structure​

Why is a resource enclosed by an element and is not a "flatter" structure? For example, assetDetails, locationDetails, and so on.

Clearer Structure

Some resources, such as locations, include a lot of information. When Get operations are enhanced to include related resources, encapsulating these data within semantically meaningful elements makes JSON processing more efficient. For example, a location may have associated photos, reviews, and category specific information like menus. In the future, if/when we enhance services, clearly indicating the boundary of a resource will be beneficial.

Validation reports, and in the future customer reports, inherit some content from the resources themselves. A flattened structure renders their reading/parsing less efficient.

Processing

Maintaining an entity inside a clearly defined element, separate from system calculated fields, facilitates efficient de-duplication.

A benefit of JSON is human-readability. Random ordering of elements in a flat structure is not beneficial. Encapsulation facilitates easier identification of the information types of concern.

JSON is a lightweight data-interchange format. It is easy for machines to parse and generate. If a system wanted to ignore locationDetails because it is the data a partner provided, it is easy to do that by ignoring the entire locationDetails object.

Customer Familiarity

GeoJSON, for example, is a well known standard in the geospatial industry. The data in GeoJSON format has a particular structure. It has type, geometry and properties.

Language Support​

What languages do you support?

Refer to Countries and Languages.

Location​

We aggregate Quicklinks from more than one App Store provider for the same location. How are "competing" providers handled on the place card?

When the relationship between a quicklink and location is "OWNER", then its quickLinkUrl is prioritized over others. The order of quicklinks which follow is alphabetical.


Why is an appStoreUrl expected to be included when submitting a quicklink?

The appStoreUrl is used to retrieve the logo that's associated with the provider of an app. A logo is displayed after a user selects the ellipsis (...) action button.

Apple Maps Place Card - Ellipsis (...), Menu & Logo
Apple Maps Place Card - Ellipsis (...), Menu & Logo

What is the purpose of the Category?

Category is used to identify the UI button that should be displayed to a user on the place card.


Do you plan to support delivery of App Clips via Apple Business API? Currently, we deliver these using an App Store Connect API.

Action link details was "future-proofed" to support their delivery in Apple Business. No decision has been made yet if and when we'll support this.


How is Relationship used?

Relationship is used to determine the order in which provider apps should be listed.

Call-to-Action​

What is the primary call-to-action?

This is the preferred, user-defined action that should be displayed along with other actions on the place card. Typically this is the fourth action in the row, such as Menu in this example. Refer to these recommended steps for adding a preferred call-to-action.

Apple Maps Place Card - Call To Action
Apple Maps Place Card - Call To Action

Some call-to-actions are technically supported by an App Clip and some by quickLinkUrl. We also know that providers of these applications can have different relationships with the locations. When we add a primary call-to-action, how are these factors taken into consideration?

We hid the implementation details and simplified the user experience by only "exposing" actions. Quicklinks are delivered to Apple Business using action link details. Action link details identify app providers and describe their relationship with a location. In a scenario where an action is supported by multiple providers of apps, business rules will determine which provider's app will be used to support the call-to-action.

How do I find out what the available call-to-action values are for a location prior to creating it?

We cannot tell you in advance what the available values are until we know which Apple Maps location in our system best matches your location.

The recommended process is as follows:

  • Create a location
  • Get the list of available call-to-action values
  • Update a location with the call-to-action value

What happens when a call-to-action is no longer available in the future if I successfully add one today

If relevant and available, Apple Maps selects an alternative call-to-action for your location's place card.

When we fetch calls-to-action using an API, an action is included in a response that doesn't appear valid for use with the location's primary category. Why?

This is an internal data quality issue. The issue stems, in part, from a legacy data requirement that allowed a combination of location categories and quicklink categories which today are considered invalid or illogical.

Another contributing factor to this issue is the bulk ingest process. Bulk data deliveries are not subject to "real-time" validations. For practical reasons, we do not reject a record received via the bulk ingest process because rejecting a single record requires the rejection of an entire file.

With improved monitoring of bulk deliveries and enhanced filtering of existing quicklink data made available through Apple Business API, the issue will become less pronounced over time.

What should we do when CallToActionMustBeAvailable is included in a validation report?

When this validation is triggered, it means that your selected call-to-action is not currently available for use on your location's place card. As a location owner, you may add a flexible action link to use with your call-to-action. However, the flexible action link you add must be relevant for use with the call-to-action you want to use. For example, a "Tickets" call-to-action would not be relevant when used in conjunction with a flexible action link which navigates a user to a web page with job listings.

If a call-to-action is not available at the time of the API request, why isn't the validation severity of CallToActionMustBeAvailable a VIOLATION?

It is possible, for example, to create and schedule a showcase which uses a call-to-action which doesn't exist, yet. An action link which "implements" a call-to-action could be delivered in a location resource by a provider just prior to the showcase's expected start date.

Display Names​

Primary Flag​

Is Primary name the same as the "default" name?

It depends upon your definition of default. There are over 7,000 languages spoken in the world. For the person that's speaking one of these languages, they'd consider a "default" name to be a value that's in their language. If we consider default to be a value that an external customer decides it should be, we cannot presume what it is.

Consideration of a primary name may depend upon:

  • Cultural norms
  • Historical preferences
  • Country of origin of the published data
Display NameCountryComment
Eiffel Tower/Tour EiffelFranceMay be localized in fr or en depending upon where the data is originated from and who the target consumers are. Consequently, this impacts the selection of primary
Guaranteed Rate FieldUSA"White Sox Stadium" may be culturally preferred. Optionally, "Comiskey Park," "U.S. Cellular Field," and "White Sox Park"

Display Point​

At some of our retail locations multiple brands are on display but all operate out of the same physical location. There's no separation of these brands at these locations in terms of space or equipment, and our staff are trained to help customers with service requests under our respective brands. How should we submit location information under these circumstances?

If you want to offer a customer experience that distinguishes one brand from another, you'll need to create separate locations and associate those locations with their respective brand. (A location cannot belong to more than one brand.) The locations you create may share the same descriptive details, such as address, phone number, display point, access points and so on. The distinctness in their assigned categories, brand name/logo, websites, and so on, support a "branded" user experience.

Location Status​

For a location that's moved, when we create the new location (as instructed above), can we use the same partnersLocationId?

No. You must generate a new partnersLocationId for your record. If you attempt to create a new location using the same partnersLocationId, an error will be returned.

Similarly, if you "soft" delete the location after updating its location status, an attempt to create a new location using the same partnersLocationId will also return an error.

See Partners Location ID for more information about the immutability of partnersLocationId and its re-use after deletion.


What happens if we do not update a location from OPENING_SOON to OPEN after the opening date has elapsed?

We will update location status on your behalf.


When a location has permanently closed, should we delete the location?

There are two approaches:

  • If you have an operational preference to maintain only "active" locations amongst systems, we strongly recommend that you update the location's locationStatus to CLOSED, then delete the location
  • If there's no operational constraint, our recommendation is to update the location's location status to CLOSED but do not delete the location

When a location has moved, can we simply update the address and/or display point? In effect, keeping the same Apple-generated ID/partnersLocationId combination, just updating the location details.

No, you cannot use the same location record. When a location has moved, a new location must be created. Refer to the previous question for additional information.

Opening Hours by Day​

How should opening hours that extend past midnight be modeled?

In a scenario where opening hours are 10pm-12.30am, the hours should be modeled as:

{
  "startTime": "22:00",
  "endTime": "00:30"
}

Not recommended:

{
  "startTime": "22:00",
  "endTime": "23:59"
}
{
  "startTime": "00:00",
  "endTime": "00:30"
}

Why are Opening Hours By Day only recommended? We physically close our doors at a set time, don't you require our hours?

Yes, we do require your hours. Our rules must be flexible to handle unattended locations.

Guidance

Partners Location ID​

Can we re-use a partnersLocationId after deleting a location?

Yes. However, you should not reuse a partnersLocationId for a new location until after the "soft" deleted record is physically deleted. If you attempt to create a new location using the same partnersLocationId as a "soft" deleted record, an error will be returned.

Why is partnersLocationId immutable? It's an id that we've assigned so we should have the flexibility to update when necessary.

This constraint is expected to be partially eliminated in a future release and fully eliminated at a later date. In a future release, a partnersLocationId can be updated when a partner is delegated. Partners "acting" upon their own (un-delegated) resources will continue to be unable to update partnersLocationId.

At a later date, the constraint will be entirely removed allowing update of the partnersLocationId. We may, however, monitor system activity such as mass updates, so that we can generate notifications about events that are outside the norm.

Why is partnersLocationId required when partners create locations, but not required when location owners create locations?

It is standard business practice for an un-delegated partner to assign an ID that they generate to a listing they manage on their platform. This is not always the case for location owners. Consequently, we do not enforce this data requirement.

Some partners now using our API had previously been delivering data using our bulk ingest process. To facilitate a more "seamless" transition from bulk to API, we required that they pass the site_code, assigned to a record in bulk, into the partnersLocationId field when creating a resource.

The transitional requirement that a partner pass the site_code as a partnersLocationId had the effect of also requiring that all new API users also provide a partnersLocationId, even though they had never participated in the bulk program.

We are a delegated partner. We are receiving a "Contact support team" error when trying to update a location's partnersLocationId to a value that was previously used on that same location. Why?

When a partnersLocationId is updated, the previous value is retained internally as a historical reference. Attempting to update a location's partnersLocationId to a value that was previously assigned to that location will result in a 404 REQUEST_FAILED response. This is because the previous partnersLocationId is archived for historical purposes and cannot be immediately reused on the same location, which results in a conflict.

To resolve this, use a new, unique partnersLocationId that has not previously been assigned to the location.

Place Card URL​

Does the URL have a predictable format?

Yes.

https://maps.apple.com/location?auid={auid}

{auid} is an encrypted MUID. For example:

https://maps.apple.com/location?auid=7378763904743701440

Does the URL have an expiry date?

The URL does not have an expiry date. However, the URL will become inoperable after the location is re-conflated.

Does the URL provide a "snapshot" of the place card at the time of URL creation or is it a "live" view?

While the URL is operable, you'll be provided with a "live" view of the place card.

Will the URL function in any web browser?

The URL functions in Apple Safari, Google Chrome, and Mozilla Firefox.

Why isn't placeCardUrl returned in a response body returned by a Create Location API request?

Generation of a placeCardUrl is dependent upon conflation which is a separate, offline process. Apple Business does not control when conflation happens. A placeCardUrl, when available, can be retrieved via any Get location API service.

Resource States​

You are planning to add a new resource state called PUBLISH_PAUSED. What does this state mean?

PUBLISH_PAUSED indicates that a location is paused from being published on client devices. Initially, this state will only be used to indicate that a location is contained within a map region that is temporarily or permanently “frozen.”

Permanent Freeze
A permanent freeze occurs when POIs are not displayed on Apple Maps due to legal or policy decisions. Locations within that region will not be shown.

Temporary Freeze
A temporary freeze typically occurs during map data updates. The impact upon you depends on timing:

  • Newly created location → Will not display until the region is unfrozen.
  • Updated location → The updated version will not display until the region is unfrozen. A previously published version should be visible during the freeze window.

PUBLISH_PAUSED will be supported by a new processing code PROCESSING__LocationPublishingPausedInMapRegion.

What happens to a location when a map region is "unfrozen"?

The location's resource state will transition from PUBLISH_PAUSED → PUBLISHED. The location resource is not re-validated before transitioning to PUBLISHED.

Location API​

We're a brand submitting locations via API. Some of our franchisees have registered in Apple Business. Your rules don't permit them to use API because they're individual location owners. Can we ask our franchisees to verify the information we are submitting which describes their locations?

No. Only members of your organization may view the location information you've submitted. You may invite franchisees to be a part of your organization. If they accept the invitation, and they have the appropriate permissions, then they can access your location information.

Partner Location IDs​

We're considering switching from the bulk ingestion process to API. Should partnersLocationId be the same as the site_code value we currently provide today?

Yes.

Call-to-Action​

How do I find out what the available call-to-action values (CTAs) are for a location prior to creating it?

We cannot tell you in advance what the available values are until we know which Apple Maps location in our system matches your location. The recommended process is as follows:

  • Create location
  • Using Get CTAs API, request a list of currently available CTAs
  • Update Location along with the chosen CTA

What is a Location's Place Card Call-to-Action?

Refer to glossary

Location Asset​

How many assets are permitted to be associated with a location?

  • Up to one hundred (100) GALLERY assets
  • Up to one (1) COVER_PHOTO asset

I have a new cover photo for my location. What happens when I create another location asset with the same intent?

If you choose to not delete the existing resource, when you create a location asset with an intent of COVER_PHOTO, we will replace the existing resource with the new one.


What is an original photo? Is it the photo in its original size or the photo, whether original or not, used to derive other sizes?

An original photo is expected to be both the original and the photo used to derive other sizes.


We have photos with dimensions which make them eligible for more than one photos size. For example, we have a photo size of 720x720. Potentially, we could submit medium, large and original, all pointing to the same URL. What is your recommendation in a situation like this?

We recommend the following:

  • For COVER_PHOTO and GALLERY intent, create a location asset using a single photos size
  • From among the photos sizes large, xlarge, and xxlarge, pick the single largest one that's available which "maps" to one of those photos sizes, and submit just that one with the create request

Location Assets​

I don't have a CDN. How do I associate an asset with a location?

Use one of the media services to provide us your file. When creating a location asset resource, provide the media id you obtained from a service along with information describing your asset.


How many GALLERY assets may be submitted for a location?

No more than one hundred (100) GALLERY assets should be provided.


A location asset allows reference to photos, via urls, or a single image using its identifier. What's the difference?

Image IDs are generated by media API. A photo url "points" to an external resource under your management. A photo URL must reference an image having certain dimensions that you must generate, whereas only a single image must be uploaded via the media service. We will automatically generate variants from the original file. The decision of which service to use to ingest an image is yours to make based upon your operational preferences.


Why can't I update photo or image ID references?

When you create the resource, the referenced image undergoes quality review. When the review is completed, and the referenced image is approved, the approval is applicable to the complete resource, not just the image itself. Updating the imageId or any photos url is not perceived as switching out an existing image and replacing it with another image that is exactly the same. If it was the same image, the update wouldn't have been necessary to begin with.

In a scenario where you need to "update" the referenced image, you should delete the current resource and create a new one.


We mistakenly associated the wrong descriptive information with an image. How should we resolve the issue?

You cannot update photo or image ID references, including information describing the dimensions of a photo. The recommended approach is to update the descriptive information.


I have a brand asset cover photo and a location place card cover photo. The location is associated with the brand. Which cover photo will appear on the device?

The location's place card cover photo will take precedence.

Do we have to wait for a location to be PUBLISHED before we can create and associate location assets with the location?

No. You may create a location asset but the asset will not be PUBLISHED until the location is PUBLISHED.

Notifications​

Feedback contains more details than a notification. Should the process we implement default to calling the Feedback API instead of the Notifications API?

We do not advise that you implement a process that restricts calls to only the Feedback API. You should implement business logic that leverages the limited amount of data in a notification to determine if calling the Feedback API is necessary. Refer to the Create Resource process for sequence diagrams which illustrate an optimal integration with Apple Business API.


Can different notification and feedback types be generated for the same resource simultaneously? For example, could VALIDATION_FAILURE, PROCESSING_FAILURE, and CLAIM_VALIDATION be generated at the same time for the same location (ETag) version?

Notification and feedback types are mutually exclusive. Today, only one type can be generated for a resource (ETag) version at a given time. However, you should not assume that this will always be the case. We may introduce new types in the future that can be generated simultaneously.

For the types listed above:

  • Is the data valid? No → VALIDATION_FAILURE (Stop)
  • Is the location claim legitimate? Wait for review → CLAIM_VALIDATION (Stop)
  • Can we save it? No → PROCESSING_FAILURE (Stop)

When a resource is PUBLISHED, is it safe to assume that there will be no processing failures and/or validation errors for a resource (ETag) version?

Yes, for that specific etag version. When a resource reaches the PUBLISHED state, it represents a successful terminal state for that version of the data. At that point:

  • All required synchronous validations have passed.
  • Asynchronous processing for that version has completed successfully.
  • No further PROCESSING_FAILURE or validation errors will be emitted for that etag.
  • Asynchronous validation reports with severity WARNING may still be generated, but these do not block publication and do not alter the success status of the published version.

Operational Guidance
Once you receive confirmation that a specific etag is PUBLISHED:

  • You may stop monitoring for processing failures for that version.
  • You should continue monitoring notifications for:
    • Resource state changes
    • Policy or visibility impacts
    • Future version processing outcomes

PUBLISHED guarantees successful processing of a specific version — not perpetual display under all future conditions.


How should we respond to a PROCESSING_FAILURE? The codes that are returned seem internal in nature and aren't anything the business can resolve. Should we try to re-submit the same data?

A PROCESSING_FAILURE indicates that the system encountered an unexpected condition while attempting to process the request. In most cases, this does not mean your payload is invalid. Rather, it reflects a transient or infrastructure-level condition that prevented successful completion of processing.

We intentionally surface PROCESSING_FAILURE along with a code and description for transparency. Without this signal, a location might simply fail to display on client devices with no visible explanation. By exposing the failure state, we provide explicit confirmation that:

  • The request was received.
  • Processing was attempted.
  • A specific failure condition occurred during processing.

This visibility allows you to distinguish between:

  • Validation errors (actionable on your side),
  • Suppression or policy-based states, and
  • System-level processing failures.

A recommended approach for handling these failures:

Implement an Exponential Backoff Strategy
Do not immediately re-submit the data in a tight loop. If the error is caused by a temporary resource contention or a race condition on the server side, immediate retries might fail again or trigger rate limiting.

  • How to do it: Wait a short period (say 1 second) before the first retry. If that fails, wait 2 seconds, then 4 seconds, and so on.
  • Limit your attempts: We generally recommend capping retries at 3 to 5 attempts. If it fails after the final attempt, the error is likely persistent rather than transient.

When to Escalate
If the data fails consistently after your retry threshold (say 3 failed attempts spaced out over time), do not continue to re-submit.

At this point, you should contact Apple Business Support. When you do, please provide:

  1. The Apple Request ID returned in the response headers.
  2. The specific code and error message returned in the body.
  3. A sample of the JSON payload that caused the failure.

This context is vital for our engineering teams to trace the specific transaction through the internal logs and identify why the processor is failing.

Why We Expose PROCESSING_FAILURE
In scenarios where a location is not visible on a client device, the underlying reason may be a processing state. By exposing PROCESSING_FAILURE, we avoid silent failures and give you diagnostic insight into why the location is not currently published.

Our goal is to make system state observable — even when the root cause is internal — so you can:

  • Differentiate between data issues and platform issues.
  • Avoid unnecessary troubleshooting.
  • Escalate with meaningful diagnostic context when required.

We want to poll for status changes on individual locations after their submission. Should we use one of the Get (location) by ID services, the Get Feedback or Notifications services?

If you're only interested in learning about resource state changes, instead of repeatedly calling a Get (location) service, or repeatedly checking for Feedback, you may use the Notifications API. Changes in resource state, amongst other changes, will trigger the generation of a notification. By configuring your systems to periodically call the Notifications API with a "rolling" time period, we can respond with all reported changes during your specified time frame.


Why does it take ~2 days for a MAPS_DISPLAY notification to appear?

This is expected behavior. When a change is submitted, it goes through an internal validation pipeline before it is eligible to be published to Maps. That pipeline enforces a processing window of minimum 24 hours, maximum 48 hours from the time the change was submitted. Once the change clears that window and passes validation, it is published and the notification becomes available.

In your case, the ~40 hour gap between submission and the notification appearing falls within the expected range.

See next FAQ about polling for notifications to ensure you capture all notifications reliably.


Why does the createdDate on the notification predate when I was actually able to query it?

The createdDate reflects when the underlying change was submitted — not when it completed processing or became live. Because the publishing pipeline can take up to 48 hours, a notification may have a createdDate that is significantly earlier than when it first appears in your query results.

This means polling for notifications using a tight real-time window can cause you to miss events. We recommend querying with a trailing window of at least 48 hours behind real-time to ensure all notifications have had time to propagate and will be returned reliably.

The createdDate field on MAPS_DISPLAY notifications will be updated to reflect the time at which the change was published. This enhancement is expected to be available during the week of March 4, 2024. Until then, please use the above guidance for polling to ensure you capture all notifications.:::

OAuth Apps​

Authorization Code Flow​

Authorization code flow parameters do not include scope. Scope is optional according to reference documentation. Should we pass the scope parameter?

You should not pass this parameter. Scopes will be enhanced over time so excluding this parameter will eliminate a dependency.


A software "bug" re-enabled the "link accounts" feature on our platform. What are the repercussions?

If a platform user has selected to link their accounts again, it will trigger the authorization code flow. The same steps that apply when a user links accounts for the first time require completion:

  • Complete all steps described in the authorization code flow
  • Within five (5) minutes, request an access token using the authorization_code grant type
  • Make subsequent requests for new access tokens, using the refresh_token grant type, when your current access token has expired

What is the lifetime of an authorization code?

Five (5) minutes

Client Secret​

If there's a security breach and we need to regenerate a client secret, what is the estimated amount of time that existing sessions will remain open?

An established communication session will remain open for up to sixty (60) minutes. A new communication session cannot be initiated until the new client secret has been added to the partner's codebase.

Delegation vs OAuth​

Which "flavor" of OAuth are you referring to when describing an OAuth App?

We are referring to the OAuth 2.0 Authorization Framework and the authorization_code grant type, as defined in RFC 6749. This protocol flow is also referred to as "three-legged OAuth."


What is the difference between a Apple Business OAuth App and a Apple Business service account? Technically, they're both OAuth Apps.

Yes, they're both OAuth Apps. To improve disambiguation between different OAuth flows, the term "OAuth App" describes a system that facilitates the authorization code flow ("three-legged OAuth").

"Service Account" describes a system that facilitates access to resources when signed requests for resources are received ("two-legged OAuth").


How is delegation handled by OAuth?

Users and third-party partners should be cautioned about the following constraints and allowances:

  • A user cannot explicitly delegate a third-party partner during the authorization code flow
  • A user cannot use the delegation process in the Apple Business portal to configure allowable scopes
  • When a user's intent is to assign resource management authority to a third-party partner, linking accounts will give the third-party partner permissions to do exactly the same as what the user can do via their platform. Linking respective accounts assigns authority to the third-party partner much like delegation.
  • A user that does not want to assign resource management authority to a third-party partner has to assume that a partner will not independently call a Apple Business API without their knowledge or consent

In the future, we'll introduce features to allow greater control over what the third-party partner can access, and when access is granted, what they can do on your behalf.


Are OAuth and delegation permissions identical?

Scoped permissions are not identical to permissions granted after delegation. The only difference is that OAuth scopes allow a third-party partner to call any brand API on behalf of a location owner. In all other respects, scoped permissions are identical to permissions granted after delegation


Is OAuth a preferred protocol for secure access to another organization's resources?

A third-party partner can create a single service account in the Apple Business portal. Using a single service account, they can call Apple Business API and manage their own resources and all delegated resources. If the security of the service account is compromised, then the vulnerability extends to all delegated resources, not just their own.

When a service account is used to manage multiple brands belonging to the same or different organizations, the absence of partner-side system boundaries poses a data security risk. Apple Business is dependent upon the third-party partner to implement access control measures to prevent unauthorized access and unintentional changes.


Some users of our third-party platform also have Apple Business accounts. Should we "sell" a platform capability to allow them to link their respective accounts, giving them the option to manage their resources via our platform. Or, should we recommend delegation?

Delegation is recommended when:

  • Data managed in Apple Business is semantically unrelated to data managed in a third-party partner's platform
  • Users of your platform derive no tangible benefit from spatially "joining" data in the respective accounts

When a user decides to delegate to a third-party partner in Apple Business, your joint interactions with the data are strictly within a Apple Business context. For example, when a brand resource is delegated to you, the extent to which this same resource is described in your platform, if it exists at all, is not immediately obvious.

Joint management of a resource that exists in separate accounts creates operational issues. To name just a few:

  • Resource defined in one account may not be defined in another
  • Resource in one account may not be in (data) synch with the resource in another account
  • Duplication of effort to maintain resource parity amongst accounts

Operational issues create a demand for new features to solve these problems. A feature we expect to offer in the future is a new API to match delegated locations to locations in a partner's account. The quality of the results is dependent upon a resource's data condition as well as the functional capabilities of exact and fuzzy matching logic. Given these caveats, the solution is not foolproof.

OAuth Apps are recommended for users that want to manage resources in a single platform and see their changes securely propagated among authorized, integrated systems.


Do API web services we invoke, as the third-party partner acting on behalf of our users, differ from services we call as a delegated third-party partner?

The organization ID passed as a parameter into the URI will always be the identity of the user's organization, not your organization ID.

Linking Accounts​

A organization that's been added to Apple Business isn't available for selection by the user. This is step 7 of the Authorization code flow

Login to Apple Business and check the status of the organization. It must have been approved in order for it to be available for selection.


Is linking accounts restricted to certain organizations?

For launch, only a location owner is permitted to link accounts. During the authorization code flow, Apple Business will validate that the user is not a member of an organization that is a third-party partner.


Is linking accounts a one time event?

No. In the future, when we introduce capabilities for users to control what their partner's platforms can do on their behalf, we expect to require re-linking of the respective accounts.


Our organization manages its information in a third-party partner's platform. What is the minimum required information we must add to Apple Business for linking to be successful?

Minimally, your organization's details and one or more team members. What additional information you need to add to Apple Business depends upon how much feature parity exists between the respective systems. Meaning, for example, if you have an interest in Showcases, but your partner's platform does not support this feature, then you'd have to manage them in Apple Business.


We are considering linking accounts. We have several resources already defined in Apple Business. Do you offer any features to facilitate "mapping" of resources in a partner's platform to their corresponding representation in Apple Business? And/or features which allow us to merge them, or replace one with another?

Because no third-party partners are alike, offering custom integrations on a partner-by-partner basis does not make strategic sense for Apple Business. We defer to third-party partners to decide what features they'd like to support to support synchronization.


Who can link our platform account to our Apple Business account?

Only an administrator of the Apple Business org account may attempt to link accounts.

Notifications​

As the third-party partner, what notifications are planned to support an OAuth App?

A notification will be generated in response to the following events:

  • OAuth App is successfully created or deleted
  • Client ID is regenerated
  • The organization administrator responsible for linking accounts is removed as a team member

Notifications will be in the form of an email and will be sent to all third-party partner administrators.

OAuth App​

Who can create an OAuth App?

Only an organization administrator may create the app.

Also, only a third-party partner that already has production API access may create an OAuth App.


Is there a limit to the quantity of OAuth Apps we can create?

Not at this time.


What happens when we delete an OAuth App?

A notification is generated and emailed to all third-party partner administrators.

warning

All refresh tokens previously generated which you stored and associated with your platform users will no longer be valid for use. Third-party partners should formulate a communication/transition plan for handling this scenario.

Permissions​

Once we link accounts, can any user associated with our Apple Business account view and edit resources accessed via the third-party partner's platform?

Yes. But, limitations may exist that are related to the partner's platform itself and/or the platform user's account settings.


Will the third-party partner be able to view and edit our resources without our involvement?

Yes.

At launch, the third-party partner has permissions to do exactly the same as what you're able to do via their platform.

It is also possible for a third-party partner to call an API that does not correspond to a feature on the platform you use. For example, the platform you use may not explicitly support brand read and write capabilities. This does not mean, however, that the third-party partner could not independently call API concerned with brand resources.

In the future, we'll introduce features to allow greater control over what the third-party partner can do on your behalf.


When navigated to a screen where I allow access to my Apple Business account by the third-party partner, I'm not presented with any options to limit their access to resources.

At launch, the third-party partner has permissions to do exactly the same as what you're able to do via their platform. In the future, we will introduce features to allow greater control over what the third-party partner can access, and when access is granted, what they can do on your behalf.


If a third-party partner has permissions to do exactly the same as what we're able to do via their platform, what are those permissions?

Refer to scopes. You and the third-party partner have the same scopes/permissions.


Are there restrictions on which roles can remove Administrator users?

Yes. Only an administrator can remove another administrator.

Refresh Token​

Are refresh tokens that you generate which we store and associate with our platform users unaffected when we generate a new client secret for our OAuth App in Apple Business?

Yes. All refresh tokens issued before the generation of a new client secret will remain valid for use.


Does a refresh token expire?

Yes. After 90 days, if no recorded activity has occurred in Apple Business, the token is revoked.

Revoking Access​

Do you expect users to be able to "call," via our platform, a web service that you provide that revokes our access to their account?

No. We will require users to perform this action in Apple Business.

Security​

Are you able to differentiate between user edits, made via a third-party partner's platform, and modifications we, the partner, may perform independently?

Yes.


Are you able to deny user access to Apple Business, via our third-party partner platform, without causing any interruption to other users?

We can revoke an organization's access. We cannot, however, revoke access at an individual user-level. This action, if taken, would not cause any service interruption to other users associated with different organizations that rely upon your OAuth App to link their account to Apple Business.


When an organization administrator changes their password in Apple Business, is there any impact upon our platform's abilities to manage resources on their behalf?

No

Showcase​

A showcase is no longer displayed. What may have happened?

Possible reasons:

  • Showcase has expired
  • Showcase was deactivated by a person in your organization or a delegated entity
  • Phone number was removed from the location
  • Showcase's associated creative references a call-to-action whose technical implementation no longer exists

As a partner, can I create showcases in Apple Business?

Your ability to create showcases depends upon whether you are delegated or not. Only location owners and delegated partners may create a showcase.


The showcase appears on some devices but not others. Why?

The technical implementation for some call-to-action values is an App Clip. App Clips and App Extensions are not supported on macOS devices. Showcases enabled via App Clip or App Extension will only display on iOS devices.

Some call-to-action values are not supported in maps on the web. In these instances, the showcase will not display on the web version of the place card. However, the showcase will display on iOS and macOS devices subject to the constraints previously mentioned.


The expected formatting for the Showcase start and end time is dateTime. How is the time component interpreted when I'm creating a Showcase in one time zone for a Location that's located in another?

Your local time is not considered. The place card will display the showcase when the location's local time is 00:00 hours (midnight).

Additionally, the three (3) business day minimum to complete a Showcase review is a duration of time that's relative to a location's local time. For example, if you're physically in London and you create a Showcase at noon (GMT) that's going to run on a location in Sydney (Australian Eastern Standard Time (AEST)) which is 10PM local time, then the 3 business day requirement and scheduling of the showcase must take AEST into account, not GMT.

There's a three (3) business day minimum for us to submit a Showcase. What may we update in that 3 day window without creating a risk that the Showcase will not go "live" on the specified start date?

You may edit a Showcase up to 24 hours before a Showcase is expected to go "live." However, you'll need to reschedule the Showcase's start date to accommodate the 3 business day minimum.

Our Showcase passed all validations and the review step. If we update that Showcase, and it fails validations or the review step, would the original Showcase still be published?

No. Your update replaces the current version of the Showcase regardless of its resource state prior to publication. If issues have been reported concerning the latest version, then you must correct those issues. Only the latest version will be published which is the version that's available 24 hours before your chosen start date. If you have not corrected issues in the latest version, then it will not be published.

Remember, updates are only accepted up until the time the resource state changes to PUBLISHED. Also, don't forget the 3 business day minimum when submitting updates!


Can I reactivate a showcase that I've deactivated?

No. You may only delete a showcase once it is deactivated.


Can I retrieve an expired showcase?

Yes, using Get by ID. However, you can only retrieve a Showcase that's in EXPIRED resource state if the showcase had previously been PUBLISHED.


How do I deactivate a showcase that's "live" on a device?

Use the Deactivate service to deactivate a showcase. If a showcase is approved, then "live" should be considered to be:

  • Any time on a date that is equal to or greater than your showcase's start date, and
  • Any time on a date that is less than or equal to your showcase's end date

How do I extend a showcase?

Use the Extend service and provide an updated end date.

Remember, the maximum duration of a showcase is thirty (30) days. This is also the maximum amount of time a showcase can maintain an 'APPROVED' resource state. In a scenario where a showcase's original duration is just ten (10) days, the actual duration the showcase is approved for is 30 days. This means that if you extend the showcase, you can do so for a further twenty (20) days.

Validations​

Reports​

Can you explain the use cases you had in mind for context?

When context is included in a validation report, the validation's message will include either the key or the value of the key that directly or indirectly contributed to the triggered exception.

The purpose of the double curly braces is to distinguish, unambiguously, the portion of the message that captures the key. Partners may, based upon their operational needs, choose to localize the string that's a part of the message that "surrounds" the key.

For example, upon receipt of this message by a partner, a localized version of a message for VALIDATION__UnexpectedPrimaryPhoneNumberChange may be programmatically retrieved. Then, based upon the partner's knowledge of the location's world position and configured workflows, it may route the report details and location information to an operations team specializing in the handling of locations having particular characteristics.

Example Response Body (raw JSON)
{
  "validationReports":[
    {
      "code": "VALIDATION__UnexpectedPrimaryPhoneNumberChange",
      "severity": "WARNING",
      "message": "Primary '{{phoneNumber}}' changed between last version and latest submittal",
      "context": {
        "phoneNumber": "+12222222222"
      }
    }
  ]
}

After localization within a partner's system:

{
  "message": "'{{phoneNumber}}' cambio principal entre la última versión y el último envío"
}

Warning Severities​

WARNING exceptions are included in my validation report, but I don't think there's anything wrong with the data we provided. Do I need to do anything?

If the data submitted is "ground-truth," no action is necessary.



Why are WARNING exceptions included in my validation report? I'm 100% sure my data is accurate

Validations do not possess:

  • Artificial intelligence
  • Awareness of partner self-confidence or the level of trust we associate with your data
  • Knowledge of ground-truth at the exact position where a location exists
  • Intellect to help discern the difference between what is "...typically normal..." from "...typically wrong..." when "typically," by definition, is not absolute

Validations only have access to:

  • Information you've provided describing the resource
  • Information provided in related resources
  • Reference lists we maintain which facilitate a comparison of the provided information with a "benchmark"
  • Models of physical or conceptual realities such as map data defining state boundaries, localities, water bodies, ISO standards, RFC standards, and so on

The difference between Violations and Warnings is that Violations are premised upon an accepted truth, an established norm, or strict policy. For example:

  • It is physically impossible for a display point to be contained by a country that is not the same as the country in the address
  • State must be present. Without it, we can't identify where Springfield is located
  • Vulgar words and hate speech are not accepted

Warning severity accommodates the possibility that the data provided is correct when anecdotal experience suggests it could or is likely incorrect.

A brand owner describing a location physically located on a quayside is not going to necessarily understand why AccessPointsForDrivingContainedByWaterFeature is being triggered. The user has:

  • None or limited awareness of variances in spatial map data quality and map data completeness
  • None or limited understanding that zoom level is important when setting the access point

AccessPointsForDrivingContainedByWaterFeature illustrates a problem whose origin could be:

  • Data originator (location owner) not positioning the point on the "right" side of the land/water boundary
  • Map data provided to the location owner being incomplete or imprecise
  • Decimal precision adjustments by a partner
  • The receiving company having map data that is more or less precise/complete than the data originally used to capture the coordinates

A partner submitting a showcase description that includes the words "...that that..." in a sentence may benefit from DescriptionsText_SuspectedUnintentionalSequentialWordRepetition being triggered. On the other hand, when the first "that" is used as a conjunction and the second "that" is a demonstrative pronoun, the sentence is grammatically correct. The validation does not possess the intelligence of an English grammar expert.

Copyright © 2026 Apple Inc. All rights reserved.