AppleBusinessRegistry (apple_business_registry v0.3.0)

Copy Markdown View Source

Elixir client for the Apple Business Registry API.

The public surface is intentionally small:

AppleBusinessRegistry.list_businesses()
AppleBusinessRegistry.get_business("business_id")
AppleBusinessRegistry.create_business(%{name: "Acme Inc", ...})
AppleBusinessRegistry.update_business("business_id", %{name: "Acme Corp", ...})
AppleBusinessRegistry.delete_business("business_id")
AppleBusinessRegistry.list_locations("business_id")
AppleBusinessRegistry.get_location("business_id", "location_id")
AppleBusinessRegistry.token()

Configuration

config :apple_business_registry,
  team_id: System.get_env("APPLE_TEAM_ID"),
  key_id: System.get_env("BUSINESS_REGISTRY_KEY_ID"),
  private_key: System.get_env("BUSINESS_REGISTRY_PRIVATE_KEY"),
  base_url: "https://businessregistry.apple.com",
  token_ttl_seconds: 300

Every function also accepts per-call opts that override the application config.

Summary

Types

opts()
response()

Functions

create_business(attrs, opts \\ [])

Create a new business registration.

create_location(business_id, attrs, opts \\ [])

Create a new location for a business.

delete_business(business_id, opts \\ [])

Delete a business registration.

delete_location(business_id, location_id, opts \\ [])

Delete a location.

get_business(business_id, opts \\ [])

Get details for a specific business.

get_location(business_id, location_id, opts \\ [])

Get details for a specific location.

list_businesses(opts \\ [])

List all businesses registered to your team.

list_locations(business_id, opts \\ [])

List all locations for a business.

search_businesses(query, opts \\ [])

Search for businesses by name, phone, or other criteria.

token(opts \\ [])

Return a cached-per-call Apple Business Registry access token (after the JWT → token exchange).

update_business(business_id, attrs, opts \\ [])

Update an existing business registration.

update_location(business_id, location_id, attrs, opts \\ [])

Update an existing location.

validate_business(attrs, opts \\ [])

Validate a business registration before creating it.

validate_location(attrs, opts \\ [])

Validate a location before creating it.

Types

opts()

@type opts() :: keyword()

response()

@type response() :: {:ok, map()} | {:error, term()}

Functions

create_business(attrs, opts \\ [])

@spec create_business(map(), opts()) :: response()

Create a new business registration.

Parameters

  • attrs: Map of business attributes including:
    • name (required): Business name
    • organization_type: Organization type (e.g., "company", "nonprofit")
    • primary_phone: Primary contact phone number
    • primary_email: Primary contact email
    • website: Business website URL
    • description: Business description

Examples

AppleBusinessRegistry.create_business(%{
  name: "Acme Inc",
  organization_type: "company",
  primary_phone: "+1-555-123-4567",
  primary_email: "contact@acme.com"
})

create_location(business_id, attrs, opts \\ [])

@spec create_location(String.t(), map(), opts()) :: response()

Create a new location for a business.

Parameters

  • business_id: The unique identifier of the business
  • attrs: Map of location attributes including:
    • name (required): Location name
    • address (required): Street address
    • locality: City/locality
    • administrative_area: State/province
    • postal_code: Postal code
    • country: ISO country code
    • phone: Location phone number
    • latitude: Latitude coordinate
    • longitude: Longitude coordinate

Examples

AppleBusinessRegistry.create_location("biz_123", %{
  name: "Acme HQ",
  address: "1 Infinite Loop",
  locality: "Cupertino",
  administrative_area: "CA",
  postal_code: "95014",
  country: "US",
  latitude: 37.3318,
  longitude: -122.0312
})

delete_business(business_id, opts \\ [])

@spec delete_business(String.t(), opts()) :: :ok | {:error, term()}

Delete a business registration.

Parameters

  • business_id: The unique identifier of the business to delete

delete_location(business_id, location_id, opts \\ [])

@spec delete_location(String.t(), String.t(), opts()) :: :ok | {:error, term()}

Delete a location.

Parameters

  • business_id: The unique identifier of the business
  • location_id: The unique identifier of the location to delete

get_business(business_id, opts \\ [])

@spec get_business(String.t(), opts()) :: response()

Get details for a specific business.

Parameters

  • business_id: The unique identifier of the business

get_location(business_id, location_id, opts \\ [])

@spec get_location(String.t(), String.t(), opts()) :: response()

Get details for a specific location.

Parameters

  • business_id: The unique identifier of the business
  • location_id: The unique identifier of the location

list_businesses(opts \\ [])

@spec list_businesses(opts()) :: {:ok, [map()]} | {:error, term()}

List all businesses registered to your team.

Returns a list of business maps. Use decode: true to get Business structs.

list_locations(business_id, opts \\ [])

@spec list_locations(String.t(), opts()) :: {:ok, [map()]} | {:error, term()}

List all locations for a business.

Parameters

  • business_id: The unique identifier of the business

Returns a list of location maps. Use decode: true to get Location structs.

search_businesses(query, opts \\ [])

@spec search_businesses(String.t(), opts()) :: {:ok, [map()]} | {:error, term()}

Search for businesses by name, phone, or other criteria.

Parameters

  • query: Search query string
  • opts: Optional search parameters:
    • :filters: Map of filter criteria (e.g., %{country: "US"})

Examples

AppleBusinessRegistry.search_businesses("coffee", filters: %{country: "US", locality: "San Francisco"})

token(opts \\ [])

@spec token(opts()) :: {:ok, String.t()} | {:error, term()}

Return a cached-per-call Apple Business Registry access token (after the JWT → token exchange).

update_business(business_id, attrs, opts \\ [])

@spec update_business(String.t(), map(), opts()) :: response()

Update an existing business registration.

Parameters

  • business_id: The unique identifier of the business
  • attrs: Map of business attributes to update

update_location(business_id, location_id, attrs, opts \\ [])

@spec update_location(String.t(), String.t(), map(), opts()) :: response()

Update an existing location.

Parameters

  • business_id: The unique identifier of the business
  • location_id: The unique identifier of the location
  • attrs: Map of location attributes to update

validate_business(attrs, opts \\ [])

@spec validate_business(map(), opts()) :: {:ok, map()} | {:error, term()}

Validate a business registration before creating it.

Parameters

  • attrs: Map of business attributes to validate

Returns {:ok, validation_result} if validation passes, or {:error, reason} if it fails.

validate_location(attrs, opts \\ [])

@spec validate_location(map(), opts()) :: {:ok, map()} | {:error, term()}

Validate a location before creating it.

Parameters

  • attrs: Map of location attributes to validate

Returns {:ok, validation_result} if validation passes, or {:error, reason} if it fails.