listingsapi 0.5.0__py3-none-any.whl

listingsapi/resources/connected_accounts.py

@@ -0,0 +1,157 @@
+"""Connected accounts resource — client.connected_accounts.*"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from listingsapi._types import APIObject
+from listingsapi._utils import encode_location_id
+from listingsapi.resources._base import APIResource
+
+
+class ConnectedAccounts(APIResource):
+    """Manage Google and Facebook connected accounts.
+
+    Example:
+        accounts = client.connected_accounts.list()
+        url = client.connected_accounts.connect_google("https://ok.com", "https://err.com")
+    """
+
+    def list(
+        self,
+        *,
+        publisher: str | None = None,
+        status: str | None = None,
+        page: int | None = None,
+        per_page: int | None = None,
+    ) -> APIObject:
+        """Get connected third-party accounts with optional filters."""
+        params: dict[str, Any] = {}
+        if publisher is not None:
+            params["publisher"] = publisher
+        if status is not None:
+            params["status"] = status
+        if page is not None:
+            params["page"] = page
+        if per_page is not None:
+            params["perPage"] = per_page
+        data = self._get("connected-accounts", params)
+        return APIObject(data.get("data", {}).get("connectedAccountsInfo") or {})
+
+    def details(self, connected_account_id: str) -> APIObject:
+        """Get details for a connected account."""
+        data = self._get(f"connected-accounts/{connected_account_id}/details")
+        return APIObject(data.get("data", {}).get("connectedAccountDetails") or {})
+
+    def folders(self, connected_account_id: str, *, folder_name: str | None = None) -> list[APIObject]:
+        """Get folders under a connected Google account."""
+        params: dict[str, str] = {}
+        if folder_name is not None:
+            params["folderName"] = folder_name
+        data = self._get(f"connected-accounts/{connected_account_id}/folders", params)
+        items = data.get("data", {}).get("getFoldersUnderGoogleAccount") or []
+        return [APIObject(item) for item in items]
+
+    def suggestions(
+        self, connected_account_id: str, *, page: int | None = None, per_page: int | None = None
+    ) -> APIObject:
+        """Get suggested matches between a connected account's listings and listingsAPI locations."""
+        params: dict[str, Any] = {}
+        if page is not None:
+            params["page"] = page
+        if per_page is not None:
+            params["perPage"] = per_page
+        data = self._get(f"connected-accounts/{connected_account_id}/connection-suggestions", params)
+        return APIObject(data.get("data", {}).get("connectionSuggestionsForAccount") or {})
+
+    def listings(
+        self,
+        connected_account_id: str,
+        *,
+        location_info: str | None = None,
+        page: int | None = None,
+        per_page: int | None = None,
+    ) -> APIObject:
+        """Get listings the connected account has access to."""
+        payload: dict[str, Any] = {"connectedAccountId": connected_account_id}
+        if location_info is not None:
+            payload["locationInfo"] = location_info
+        if page is not None:
+            payload["page"] = page
+        if per_page is not None:
+            payload["perPage"] = per_page
+        data = self._post("connected-accounts/connected-account-listings", payload)
+        return APIObject(data.get("data", {}).get("connectedAccountListings") or {})
+
+    def connect_google(self, success_url: str, error_url: str) -> APIObject:
+        """Get a URL to connect a Google account. Valid 24 hours."""
+        data = self._post(
+            "connected-accounts/connect-google",
+            {"input": {"successUrl": success_url, "errorUrl": error_url}},
+        )
+        return APIObject(data.get("data", {}).get("bulkConnectLinkForGoogle") or {})
+
+    def connect_facebook(self, success_url: str, error_url: str) -> APIObject:
+        """Get a URL to connect a Facebook account. Valid 24 hours."""
+        data = self._post(
+            "connected-accounts/connect-facebook",
+            {"input": {"successUrl": success_url, "errorUrl": error_url}},
+        )
+        return APIObject(data.get("data", {}).get("bulkConnectLinkForFacebook") or {})
+
+    def disconnect_google(self, connected_account_id: str) -> APIObject:
+        """Disconnect a Google connected account."""
+        data = self._post(
+            "connected-accounts/disconnect-google",
+            {"input": {"connectedAccountId": connected_account_id}},
+        )
+        return APIObject(data.get("data", {}).get("gmbBulkDisconnect") or {})
+
+    def disconnect_facebook(self, connected_account_id: str) -> APIObject:
+        """Disconnect a Facebook connected account."""
+        data = self._post(
+            "connected-accounts/disconnect-facebook",
+            {"input": {"connectedAccountId": connected_account_id}},
+        )
+        return APIObject(data.get("data", {}).get("fbBulkDisconnect") or {})
+
+    def trigger_matches(self, connected_account_ids: list[str]) -> APIObject:
+        """Trigger matching of profiles to listingsAPI locations."""
+        data = self._post(
+            "connected-accounts/trigger-matches",
+            {"input": {"connectedAccountIds": connected_account_ids}},
+        )
+        return APIObject(data.get("data", {}).get("connectedAccountsTriggerMatches") or {})
+
+    def confirm_matches(self, match_record_ids: list[str]) -> APIObject:
+        """Confirm suggested matches between connected account listings and locations."""
+        data = self._post(
+            "connected-accounts/confirm-matches",
+            {"input": {"matchRecordIds": match_record_ids}},
+        )
+        return APIObject(data.get("data", {}).get("confirmConnectMatches") or {})
+
+    def oauth_url(
+        self, location_id: str | int, site: str, success_url: str, error_url: str
+    ) -> APIObject:
+        """Get a URL to connect a Google/Facebook profile to a single location. Valid 24 hours."""
+        data = self._post(
+            "locations/oauth_connect_url",
+            {
+                "input": {
+                    "locationId": encode_location_id(location_id),
+                    "site": site.upper(),
+                    "successUrl": success_url,
+                    "errorUrl": error_url,
+                }
+            },
+        )
+        return APIObject(data.get("data", {}).get("connectUrl") or {})
+
+    def oauth_disconnect(self, location_id: str | int, site: str) -> APIObject:
+        """Disconnect a Google/Facebook profile from a single location."""
+        data = self._post(
+            "locations/oauth-disconnect",
+            {"input": {"locationId": encode_location_id(location_id), "site": site.upper()}},
+        )
+        return APIObject(data.get("data", {}).get("disconnectConnectedAccountsLocations") or {})

listingsapi/resources/listings.py

@@ -0,0 +1,101 @@
+"""Listings resource — client.listings.*"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from listingsapi._types import APIObject
+from listingsapi._utils import encode_location_id
+from listingsapi.resources._base import APIResource
+
+
+class Listings(APIResource):
+    """Manage directory listings for locations.
+
+    Example:
+        listings = client.listings.premium(16808)
+        for listing in listings:
+            print(listing.site, listing.syncStatus)
+    """
+
+    def premium(self, location_id: str | int) -> list[APIObject]:
+        """Get premium directory listings (Google, Yelp, etc.)."""
+        data = self._location_get(location_id, "listings/premium")
+        items = data.get("data", {}).get("listingsForLocation") or []
+        return [APIObject(item) for item in items]
+
+    def voice(self, location_id: str | int) -> list[APIObject]:
+        """Get voice assistant listings (Google, Alexa, Siri)."""
+        data = self._location_get(location_id, "voice-assistants")
+        items = data.get("data", {}).get("voiceAssistantsForLocation") or []
+        return [APIObject(item) for item in items]
+
+
+    def duplicates(self, location_id: str | int) -> list[APIObject]:
+        """Get duplicate listings for a location."""
+        data = self._location_get(location_id, "listings/duplicates")
+        items = data.get("data", {}).get("duplicateListingsForLocation") or []
+        return [APIObject(item) for item in items]
+
+    def all_duplicates(self, *, tag: str | None = None, page: int | None = None) -> APIObject:
+        """Get duplicate listings across all locations."""
+        params: dict[str, Any] = {}
+        if tag is not None:
+            params["tag"] = tag
+        if page is not None:
+            params["page"] = page
+        data = self._get("locations/listings/duplicates", params)
+        return APIObject(data.get("data", {}).get("duplicateListingsRollup") or {})
+
+    def mark_duplicate(self, location_id: str | int, listing_item_ids: list[str]) -> APIObject:
+        """Mark listing items as duplicates."""
+        data = self._post(
+            "locations/listings/mark-as-duplicate",
+            {"input": {"locationId": encode_location_id(location_id), "listingItemIds": listing_item_ids}},
+        )
+        return APIObject(data.get("data", {}).get("markAsDuplicate") or {})
+
+    def mark_not_duplicate(self, location_id: str | int, listing_item_ids: list[str]) -> APIObject:
+        """Clear duplicate status for listing items."""
+        data = self._post(
+            "locations/listings/mark-as-not-duplicate",
+            {"input": {"locationId": encode_location_id(location_id), "listingItemIds": listing_item_ids}},
+        )
+        return APIObject(data.get("data", {}).get("markAsNotDuplicate") or {})
+
+    def connect(
+        self, location_id: str | int, connected_account_listing_id: str, connected_account_id: str
+    ) -> APIObject:
+        """Link a location to a listing from a connected account."""
+        data = self._post(
+            "connected-accounts/connect-listing",
+            {
+                "input": {
+                    "locationId": encode_location_id(location_id),
+                    "connectedAccountListingId": connected_account_listing_id,
+                    "connectedAccountId": connected_account_id,
+                }
+            },
+        )
+        return APIObject(data.get("data", {}).get("connectListing") or {})
+
+    def disconnect(self, location_id: str | int, site: str) -> APIObject:
+        """Disconnect a location from its Google or Facebook listing."""
+        data = self._post(
+            "connected-accounts/disconnect-listing",
+            {"input": {"locationId": encode_location_id(location_id), "site": site.upper()}},
+        )
+        return APIObject(data.get("data", {}).get("disconnectConnectedAccountsLocations") or {})
+
+    def create_gmb(
+        self, location_id: str | int, connected_account_id: str, *, folder_id: str | None = None
+    ) -> APIObject:
+        """Create a Google Business Profile listing for an existing location."""
+        payload: dict[str, Any] = {
+            "locationId": encode_location_id(location_id),
+            "connectedAccountId": connected_account_id,
+        }
+        if folder_id is not None:
+            payload["folderId"] = folder_id
+        data = self._post("locations/create/gmb-listing", {"input": payload})
+        return APIObject(data.get("data", {}).get("createGmbListingForLocation") or {})

listingsapi/resources/locations.py

@@ -0,0 +1,296 @@
+"""Locations resource — client.locations.*"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from listingsapi._types import APIObject, SyncPage
+from listingsapi._utils import encode_location_id
+from listingsapi.resources._base import APIResource
+
+
+class Locations(APIResource):
+    """Manage locations.
+
+    Example:
+        # List locations
+        page = client.locations.list(first=10)
+        for loc in page:
+            print(loc.name, loc.city)
+
+        # Auto-paginate
+        for loc in client.locations.list(first=50).auto_paging_iter():
+            print(loc.name)
+
+        # Create
+        result = client.locations.create({"name": "Acme", "street": "123 Main St", ...})
+    """
+
+    def list(
+        self,
+        *,
+        first: int | None = None,
+        after: str | None = None,
+        before: str | None = None,
+        last: int | None = None,
+    ) -> SyncPage:
+        """List locations with cursor-based pagination.
+
+        Returns:
+            SyncPage of location objects. Use .auto_paging_iter() to iterate all.
+        """
+        params: dict[str, Any] = {}
+        if first is not None:
+            params["first"] = first
+        if after is not None:
+            params["after"] = after
+        if before is not None:
+            params["before"] = before
+        if last is not None:
+            params["last"] = last
+
+        data = self._get("locations", params)
+        all_locs = data.get("data", {}).get("allLocations") or {}
+        edges = all_locs.get("edges") or []
+        page_info = all_locs.get("pageInfo") or {}
+        items = [edge["node"] for edge in edges]
+        end_cursor = edges[-1]["cursor"] if edges else None
+
+        return SyncPage(
+            data=items,
+            has_more=page_info.get("hasNextPage", False),
+            end_cursor=end_cursor,
+            total=page_info.get("total"),
+            _fetch_next=lambda cursor: self.list(first=first, after=cursor),
+        )
+
+    def retrieve(self, location_id: str | int) -> APIObject:
+        """Get a single location by ID.
+
+        Args:
+            location_id: Numeric (e.g. 16808) or base64-encoded ID.
+        """
+        results = self.list_by_ids([location_id])
+        if not results:
+            from listingsapi.exceptions import NotFoundError
+
+            raise NotFoundError(f"Location {location_id} not found", status_code=404)
+        return results[0]
+
+    def list_by_ids(self, location_ids: list[str | int]) -> list[APIObject]:
+        """Get locations by a list of IDs (numeric or base64)."""
+        if not location_ids:
+            return []
+        encoded = [encode_location_id(lid) for lid in location_ids]
+        data = self._get("locations-by-ids", {"ids": json.dumps(encoded)})
+        items = data.get("data", {}).get("getLocationsByIds") or []
+        return [APIObject(item) for item in items]
+
+    def list_by_store_codes(self, store_codes: list[str]) -> list[APIObject]:
+        """Get locations matching the given store codes."""
+        if not store_codes:
+            return []
+        data = self._get("locations-by-store-codes", {"storeCodes": json.dumps(store_codes)})
+        items = data.get("data", {}).get("getLocationsByStoreCodes") or []
+        return [APIObject(item) for item in items]
+
+    def search(
+        self,
+        query: str,
+        *,
+        fields: list[str] | None = None,
+        first: int | None = None,
+        after: str | None = None,
+        before: str | None = None,
+        last: int | None = None,
+    ) -> SyncPage:
+        """Search locations by keyword (name, address, or store ID).
+
+        Args:
+            query: Search term.
+            fields: Restrict search to specific fields (e.g. ["name"], ["store_id"]).
+        """
+        params: dict[str, Any] = {"query": query}
+        if fields is not None:
+            params["fields"] = json.dumps(fields)
+        if first is not None:
+            params["first"] = first
+        if after is not None:
+            params["after"] = after
+        if before is not None:
+            params["before"] = before
+        if last is not None:
+            params["last"] = last
+
+        data = self._get("locations/search", params)
+        result = data.get("data", {}).get("searchLocations") or {}
+        edges = result.get("edges") or []
+        page_info = result.get("pageInfo") or {}
+        items = [e["node"] for e in edges]
+        end_cursor = edges[-1]["cursor"] if edges else None
+
+        return SyncPage(
+            data=items,
+            has_more=page_info.get("hasNextPage", False),
+            end_cursor=end_cursor,
+            total=page_info.get("total"),
+            _fetch_next=lambda cursor: self.search(query, fields=fields, first=first, after=cursor),
+        )
+
+
+
+    def create(self, input: dict[str, Any]) -> APIObject:
+        """Create a new location from a raw input dict. Pass camelCase field names.
+
+        Required by the API: name, description (min 200 characters), subCategoryId,
+        countryIso, and city (for countries with city-level addressing). Prefer
+        locations.add() for keyword arguments and client-side validation.
+
+        Args:
+            input: Location data dict with camelCase keys.
+        """
+        data = self._post("locations", {"input": input})
+        return APIObject(data.get("data", {}).get("createLocation") or {})
+
+    def add(
+        self,
+        *,
+        name: str,
+        description: str,
+        sub_category_id: int,
+        country_iso: str,
+        city: str | None = None,
+        street: str | None = None,
+        state_iso: str | None = None,
+        postal_code: str | None = None,
+        phone: str | None = None,
+        website: str | None = None,
+        store_id: str | None = None,
+        hide_address: bool | None = None,
+        business_hours: list[dict[str, Any]] | None = None,
+        folder_ids: list[str] | None = None,
+        service_area: dict[str, Any] | None = None,
+        place_action_links: list[dict[str, Any]] | None = None,
+        enabled_site_ids: list[int] | None = None,
+        additional_fields: dict[str, Any] | None = None,
+    ) -> APIObject:
+        """Create a location in one call with every mandatory field as a keyword argument.
+
+        Validates the API's create requirements client-side and raises ValidationError
+        before any network call, so a bad payload fails fast with a clear message.
+
+        Args:
+            name: Business name, 2-150 characters.
+            description: Business description, minimum 200 characters. Publishers use
+                it as the primary listing copy.
+            sub_category_id: Primary subcategory ID (see the subcategories endpoint
+                for valid IDs).
+            country_iso: Two-letter country ISO code (must be a supported country).
+            city: City. Required for countries with city-level addressing; may be
+                omitted only for service-area businesses with hide_address=True.
+            street: Street address.
+            state_iso: State/region ISO code.
+            postal_code: Postal or ZIP code.
+            phone: Primary phone number, validated for the country.
+            website: Business website URL.
+            store_id: Your unique store code; must be unique across the account.
+            hide_address: Hide the street address (service-area businesses).
+            business_hours: Weekly hours, e.g. [{"day": "MONDAY", "slots": [...]}].
+            folder_ids: Folder IDs to place the location in.
+            service_area: Service-area config: {businessType, regionCode, placeInfos}.
+            place_action_links: Google action links, e.g.
+                [{"placeActionType": "APPOINTMENT", "uri": "https://...", "isPreferred": True}].
+            enabled_site_ids: Site IDs to publish this location to, when you want a
+                subset of your plan's sites (see the plan-sites endpoint for IDs).
+            additional_fields: Extra camelCase fields merged into the payload as-is.
+
+        Returns:
+            The createLocation payload; .location holds the new location and .success
+            is True on success.
+
+        Example:
+            result = client.locations.add(
+                name="Acme Dental",
+                description="Acme Dental is a family-owned dental practice...",  # 200+ chars
+                sub_category_id=1432,
+                country_iso="US",
+                city="New York",
+                street="123 Jump Street",
+                postal_code="10013",
+                phone="6443859313",
+            )
+            print(result.location.id)
+        """
+        problems: list[str] = []
+        if not name or not (2 <= len(name.strip()) <= 150):
+            problems.append("name must be 2-150 characters")
+        if not description or len(description.strip()) < 200:
+            got = len(description.strip()) if description else 0
+            problems.append(f"description must be at least 200 characters (got {got})")
+        if not sub_category_id:
+            problems.append("sub_category_id is required")
+        if not country_iso or not str(country_iso).strip():
+            problems.append("country_iso is required")
+        if not (city and city.strip()) and hide_address is not True:
+            problems.append(
+                "city is required for countries with city-level addressing "
+                "(omit only for service-area businesses with hide_address=True)"
+            )
+        if problems:
+            from listingsapi.exceptions import ValidationError
+
+            raise ValidationError("Invalid location: " + "; ".join(problems))
+
+        input: dict[str, Any] = {
+            "name": name.strip(),
+            "description": description.strip(),
+            "subCategoryId": sub_category_id,
+            "countryIso": country_iso,
+        }
+        optional = {
+            "city": city,
+            "street": street,
+            "stateIso": state_iso,
+            "postalCode": postal_code,
+            "phone": phone,
+            "website": website,
+            "storeId": store_id,
+            "hideAddress": hide_address,
+            "businessHours": business_hours,
+            "folderIds": folder_ids,
+            "serviceArea": service_area,
+            "placeActionLinks": place_action_links,
+            "enabledSiteIds": enabled_site_ids,
+        }
+        input.update({k: v for k, v in optional.items() if v is not None})
+        if additional_fields:
+            input.update(additional_fields)
+
+        return self.create(input)
+
+    def update(self, input: dict[str, Any]) -> APIObject:
+        """Update a location. Pass id plus fields to change."""
+        if "id" in input:
+            input = {**input, "id": encode_location_id(input["id"])}
+        data = self._post("locations/update", {"input": input})
+        return APIObject(data.get("data", {}).get("updateLocation") or {})
+
+    def archive(self, location_ids: list[str | int]) -> APIObject:
+        """Archive one or more locations."""
+        encoded = [encode_location_id(lid) for lid in location_ids]
+        data = self._post("locations/archive", {"input": {"locationIds": encoded}})
+        return APIObject(data.get("data", {}).get("archiveLocations") or {})
+
+
+    def cancel_archive(
+        self, location_ids: list[str | int], selection_type: str, changed_by: str
+    ) -> APIObject:
+        """Cancel a scheduled archival."""
+        encoded = [encode_location_id(lid) for lid in location_ids]
+        data = self._post(
+            "locations/cancel_archive",
+            {"input": {"locationIds": encoded, "selectionType": selection_type, "changedBy": changed_by}},
+        )
+        return APIObject(data.get("data", {}).get("cancelLocationsArchive") or {})
+

listingsapi/resources/photos.py

@@ -0,0 +1,53 @@
+"""Photos resource — client.photos.*"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from listingsapi._types import APIObject
+from listingsapi._utils import encode_location_id
+from listingsapi.resources._base import APIResource
+
+
+class Photos(APIResource):
+    """Manage location photos.
+
+    Example:
+        photos = client.photos.list(16808)
+        client.photos.add(16808, [{"photo": "https://example.com/img.jpg", "type": "ADDITIONAL"}])
+    """
+
+    def list(self, location_id: str | int) -> list[APIObject]:
+        """Get photos attached to a location."""
+        data = self._location_get(location_id, "photos")
+        items = data.get("data", {}).get("mediaFilesOfLocation") or []
+        return [APIObject(item) for item in items]
+
+    def add(self, location_id: str | int, photos: list[dict[str, Any]]) -> APIObject:
+        """Add photos to a location. Each item needs 'photo' (URL) and 'type' (LOGO, COVER, ADDITIONAL)."""
+        data = self._post(
+            "locations/photos",
+            {"input": {"locationId": encode_location_id(location_id), "photos": photos}},
+        )
+        return APIObject(data.get("data", {}).get("addLocationPhotos") or {})
+
+    def remove(self, location_id: str | int, photo_ids: list[str]) -> APIObject:
+        """Remove photos from a location."""
+        data = self._post(
+            "locations/photos/remove",
+            {"input": {"locationId": encode_location_id(location_id), "photoIds": photo_ids}},
+        )
+        return APIObject(data.get("data", {}).get("removeLocationPhotos") or {})
+
+    def star(self, location_id: str | int, media_ids: list[str], *, starred: bool = True) -> APIObject:
+        """Star or unstar photos. Max 4 starred photos per account."""
+        data = self._post(
+            "locations/photos/star",
+            {"input": {"locationId": encode_location_id(location_id), "mediaIds": media_ids, "starred": starred}},
+        )
+        return APIObject(data.get("data", {}).get("starUnstarLocationPhotos") or {})
+
+    def upload_status(self, request_id: str) -> APIObject:
+        """Get processing status for a bulk photo upload."""
+        data = self._get(f"locations/photos/requests/{request_id}")
+        return APIObject(data.get("data", {}).get("bulkImageProcessingStatus") or {})