Manage Google Business Profile

What these endpoints do

The /v2/gbp/ endpoints act on the Google Business Profile itself, not on Local Falcon report data. They read and write live data at Google, so a call reflects the profile exactly as it stands at that moment, and a write takes effect on the public listing.

Every endpoint is keyed on place_id and works only for locations connected to a Google account in your Local Falcon account. Use POST /v1/locations/ with gbp_linked set to true to list eligible locations.

The endpoint set

Sending parameters

Requests are form encoded. Array and object parameters are sent as indexed form fields, not as a JSON body — a JSON body is not read at all, and the call will fail as though the parameters were missing.

curl -X POST "https://api.localfalcon.com/v2/gbp/add-services/" \
  -d "api_key=YOUR_API_KEY" \
  -d "place_id=ChIJ..." \
  -d "services[0][name]=Drain cleaning" \
  -d "services[1][name]=Leak detection"

Confirmation on destructive endpoints

Six endpoints will not act unless you echo a confirmation token. Without it the request is rejected with GBP_CONFIRMATION_REQUIRED and nothing is changed, so a mistaken call is safe. The token is matched without regard to case or surrounding whitespace.

update-status also requires confirm=CLOSED_PERMANENTLY when closing a business permanently.

Response shape

Responses use the standard Local Falcon envelope, with the payload in data. Field names are snake_case, with two deliberate exceptions: POST /v2/gbp/location/ and POST /v2/gbp/google-updated/ return Google's own resource unchanged, so their fields are camelCase.

A field with no value is returned as false rather than being omitted. Times are objects, and midnight is {"hours": 0}; a period running to the end of the day closes at {"hours": 24}.

Pagination

List endpoints accept limit (1 to 100) and return a next_token when more results exist. Pass it back as next_token for the next page. When it is absent you have reached the end. A limit outside the valid range is rejected rather than clamped.

Worked example: publish a post, then remove it

Create a post on a connected location.

curl -X POST "https://api.localfalcon.com/v2/gbp/create-post/" \
  -d "api_key=YOUR_API_KEY" \
  -d "place_id=ChIJ..." \
  -d "topic_type=STANDARD" \
  -d "summary=Spring service checks are now open for booking."

The response returns a post_id. Deleting it without the confirmation token is refused, and the post stays live.

curl -X POST "https://api.localfalcon.com/v2/gbp/delete-post/" \
  -d "api_key=YOUR_API_KEY" \
  -d "place_id=ChIJ..." \
  -d "post_id=7421632958301234567"

# {"code":400,"code_desc":"GBP_CONFIRMATION_REQUIRED","success":false,
#  "message":"Deleting a post cannot be undone. Pass confirm=DELETE_POST to go ahead."}

Repeat the call with the token to delete it.

curl -X POST "https://api.localfalcon.com/v2/gbp/delete-post/" \
  -d "api_key=YOUR_API_KEY" \
  -d "place_id=ChIJ..." \
  -d "post_id=7421632958301234567" \
  -d "confirm=DELETE_POST"

Things worth knowing

• Check verification first when a write is refused. has_voice_of_merchant is the practical signal: when it is false the profile is not fully in the merchant's control and Google will reject some writes.
• Action link types are category dependent. Call action-types before create-link to see what the location may use.
• Some links cannot be edited. Links Google sourced from a third party aggregator come back with is_editable set to false and cannot be changed or removed through this API.
• Services come in two forms. A free form service carries the label you chose in name; a structured one carries a Google identifier in both name and service_type_id, and structured tells them apart. The value in name is the matching key for add, remove and replace.
• Hours are independent. Sending only special leaves regular hours untouched, and special hours are keyed by date, so writing one date does not disturb the others.
• Writes merge by default. Fields you do not send are left alone. Use replace to write a field wholesale, and clear to empty one.
• Metrics lag. Google holds roughly 18 months of history and the most recent few days are usually not yet available.