Adding Google Address Override

Overview

This document describes the changes made to the buildings and companies endpoints to allow API users to override the address returned by Google. The changes apply to POST, PATCH, and GET methods.

Fields Added

The following fields have been added to the buildings and companies endpoints:

google_verification_override: A boolean flag that allows users to override the Google-verified address.

google_place_id: Stores the Google Place ID of the address.

google_formatted_address: Stores the Google-formatted address.

Affected Endpoints

organizations/vendors/{vendorId}/
/organizations/tenants/{tenantId}/
/locations/buildings/

And these models

Tenants
Vendors
Buildings

POST Method

When creating a new building or company, users can pass in the google_verification_override flag. If the flag is set to TRUE, the API will attempt to match the address with Google's geocode and places APIs. If a match is found, the google_place_id and google_formatted_address fields will be populated. The street_address, street_address_2, city, zip_code, state, and country values will be kept as they were passed in the request.

If no formatted_address (for buildings) or verified formatted address (for companies) is provided with the google_verification_override set to true, then we construct our own formatted address in the US centric way

{street_address}{street_address_2}{city},{state}{zip_code},{country}

If the google_verification_override flag is set to FALSE or null, the API will still attempt to match the address with Google's APIs. If a match is found, the google_place_id and google_formatted_address fields will be populated. The formatted_address field will be populated with the Google-formatted address, and the street_address, street_address_2, city, zip_code, state, and country will be populated with the Google response.

PATCH Method

When updating a building or company, users can pass in the google_verification_override flag. If the flag is set to TRUE and was previously FALSE or null, the API will treat new address fields passed in the PATCH call as outlined for the POST method. If the flag is set to FALSE and was previously TRUE, the API will update address fields based on the Google response.

Change Details

Tenants and Vendors

Tenants and vendors utilize the Address model. The model includes the following fields:

verified_formatted_address: This field serves as the definitive source for the final address. Previously, this value was always determined by the formatted_address returned by the Google Maps API. However, even if the user updated this value, it would be overwritten during validation.
custom_formatted_address: This field was introduced as a solution to a client-reported bug. It allows clients to use a custom address field. It also ensures that the street_address_2 field is not lost by including it in the verified_formatted_address field in brackets.

To accommodate the client's need to add tenants and vendors via the API and view the custom addresses, we have made several modifications:

google_verification_override: This new field allows users to determine if the verified_formatted_address field will be overwritten.
google_place_id and google_formatted_address: These fields store the values returned by the Google Maps API. They are stored when the google_verification_override is active, ensuring that a valid address from a trusted source (Maps API) is associated with each location.
verified_formatted_address: If the Google override is on, the user can patch any valid string into this field, which will then be displayed through the Front End.
custom_formatted_address: This field is kept equal to the verified_formatted_address if validation is on. When the user switches the google_verification_override on, we check if these values are equal and replace verified_formatted_address with the address in the constructed custom format.

Buildings

In our backend, Buildings are considered as Locations with Address fields. Buildings have their own fields similar to how locations have, but we borrow the validation process of the Address model. Buildings don’t have the address nested into an address object.

The formatted_address field and other fields like street_address, street_address_2, city, country etc are used to create an Address instance, run its validation process and then store the returned values back into the building.

To accommodate the need for a custom format, we have made several modifications:

custom_formatted_address and google_verification_override fields have been added to the Building model and are passed to the Address on its creation.
custom_formatted_address behaves the same way as described for tenants and vendors.
Address.validate_address() method is used when updating the Building. The Address instance created by this Building will have the google_place_id and the google_formatted_address stored in them.
Patching over the formatted_address is no longer possible if the google_verification_override is False, as this will trigger the validation process.
Missing fields have been added so that the Address instance created and the final formatted_address will have these values.

While the current process does involve some dangling address instances, this is acceptable given that Buildings are designed to change their address values less frequently.

Example API Calls

Here are some example API calls on how to switch the flag:

PATCH Building

curl --location --request PATCH 'http://<address>/buildings/<building_id>' \

--header 'Accept: application/json' \

--header 'Accept-Language: en-GB' \

--header 'Authorization: Bearer <token>' \

--header 'Connection: keep-alive' \

--header 'Content-Type: application/json' \

--header 'Origin: http://<address>' \

--header 'Referer: http://<address>/' \

--header 'Sec-Fetch-Dest: empty' \

--header 'Sec-Fetch-Mode: cors' \

--header 'Sec-Fetch-Site: same-site' \

--header 'User-Agent: <data> \

--header 'sec-ch-ua: <data>' \

--header 'sec-ch-ua-mobile: <data>' \

--header 'sec-ch-ua-platform: <data>' \

--data '{

"street_address": "green",

"street_address_2": "00030303",

"city": "Bengaluru",

"state": "KA",

"zip_code": "560103",

"country": "AR",

"name": "green",

"phone": "",

"measured_area": "120000 sq_ft",

"measurement_unit": "sq_ft",

"building_identifier": null,

"measurement_standard": "boma_2017_a",

"num_floors": 12,

"formatted_address": "completely custom value here",

"timezone": "Asia/Kolkata",

"year_built": null,

"units_count": null,

"access_instructions": null,

"land_area": "",

"website": null,

"description": null,

"status": "active",

"google_verification_override": true

}'

PATCH Tenant

curl --location --request PATCH 'http://<address>/organizations/tenants/<tenant_id>' \
--header 'Accept: application/json' \
--header 'Accept-Language: en-GB' \
--header 'Authorization: Bearer <token>' \
--header 'Connection: keep-alive' \
--header 'Content-Type: application/json' \
--header 'Origin: http://<address>' \
--header 'Referer: http://<address>/' \
--header 'Sec-Fetch-Dest: empty' \
--header 'Sec-Fetch-Mode: cors' \
--header 'Sec-Fetch-Site: same-site' \
--header 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36' \
--header 'sec-ch-ua: "Chromium";v="122", "Not(A:Brand";v="24", "Google Chrome";v="122"' \
--header 'sec-ch-ua-mobile: ?0' \
--header 'sec-ch-ua-platform: "macOS"' \
--data '{
"contact_name": "",
"verified": true,
"latitude": "12.929869",
"longitude": "77.684837",
"street_number": null,
"custom_formatted_address": null,
"verified_formatted_address": "Bengaluru, Karnataka 560103, India",
"google_place_id": null,
"google_formatted_address": null,
"neighborhood": null,
"county": "Bangalore Division",
"street": null,
"created_by": <user_id>,
"updated_by": <user_id>,
"url": null,
"phone": "",
"email": null,
"organization_identifier": null,
"notes": "",
"created_by_pmo": <pmo_id>,
"address": {
"street_address": "green",
"street_address_2": "333",
"city": "Bengaluru",
"state": "KA",
"zip_code": "560103",
"country": "IN",
"google_verification_override": true
}
}'

PATCH VENDOR

curl 'http://<address>/organizations/vendors/c47fec5c-6514-4b2b-a31e-3047c3706896' \
-X 'PATCH' \
-H 'Accept: application/json' \
-H 'Accept-Language: en-GB' \
-H 'Authorization: Bearer <token>' \
-H 'Connection: keep-alive' \
-H 'Content-Type: application/json' \
-H 'Origin: http://<address>' \
-H 'Referer: http://<address>/' \
-H 'Sec-Fetch-Dest: empty' \
-H 'Sec-Fetch-Mode: cors' \
-H 'Sec-Fetch-Site: same-site' \
-H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36' \
-H 'sec-ch-ua: "Chromium";v="124", "Google Chrome";v="124", "Not-A.Brand";v="99"' \
-H 'sec-ch-ua-mobile: ?0' \
-H 'sec-ch-ua-platform: "macOS"' \
--data-raw '{
"contact_name": "",
"verified": false,
"latitude": null,
"longitude": null,
"street_number": null,
"custom_formatted_address": null,
"verified_formatted_address": null,
"google_place_id": null,
"google_formatted_address": null,
"google_verification_override": false,
"neighborhood": null,
"county": null,
"street": null,
"created_by": <user_id>,
"updated_by":<user_id>,
"url": null,
"phone": "",
"email": "jdrist@gmail.com",
"organization_identifier": null,
"notes": "",
"created_by_pmo": <pmo_id>,
"vendor_classification_ids": [],
"address": {
"street_address": "dwerwrfgv",
"street_address_2": "",
"city": "Bengaluru",
"state": "AL",
"zip_code": "560103",
"country": "AR", 
"google_verification_override": true
}
}'

Overview

Fields Added

Affected Endpoints

POST Method

PATCH Method

Change Details

Tenants and Vendors

Buildings

Example API Calls

Categories

Toggle navigation menu

<%= category.name %>

Overview

Fields Added

Affected Endpoints

POST Method

PATCH Method

Change Details

Tenants and Vendors

Buildings

Example API Calls

Related articles

Categories

Toggle navigation menu

<%= category.name %>

Categories

Categories