# Updating a Location Property via the Collections API

## Overview

Adalo's Location property type stores a complete address record, not raw GPS coordinates. When writing to a Location column through the Collections API, the API expects the full address object in a specific shape. Sending only coordinates, or any partial version of the address object, results in a broken Location field that fails to display, filter, or render in map components.

This document covers how to correctly format Location property writes through the Collections API, what to do when only GPS coordinates are available, and when to use a different property type instead.

### Before You Begin

Confirm the following before writing to a Location property through the Collections API:

* The app's API key is available from the API Documentation panel (Settings, then App Access).
* The App ID and Collection ID for the target collection are known.
* The exact name of the Location property column being updated is known.
* The source data is either a complete address, or there is a way to reverse-geocode raw coordinates (for example, using Google's Geocoding API) before the API call.

The Location property requires all four of the following top-level keys in every write:

* `placeId`
* `fullAddress`
* `coordinates` (containing `latitude` and `longitude`)
* `addressElements` (containing `address1`, `address2`, `city`, `region`, `country`, `postalCode`)

Use the table below to determine which path applies before starting the walkthrough:

| Source data                         | Best column type   | What to send                                                        |
| ----------------------------------- | ------------------ | ------------------------------------------------------------------- |
| Full address text                   | Location           | Full address object (geocode first if only the string is available) |
| GPS coordinates, address needed     | Location           | Reverse-geocode, then send the full address object                  |
| GPS coordinates, address not needed | Two Number columns | `{ "Latitude": 39.78, "Longitude": -89.65 }`                        |

{% hint style="warning" %}
The Collections API does not perform reverse-geocoding on inbound writes. Whatever payload is sent is exactly what gets stored. There is no enrichment or transformation on Adalo's side. 
{% endhint %}

## Walkthrough

#### Identify the right endpoint

Use the following endpoint depending on whether the request is creating or updating a record:

* **Create record:** `POST https://api.adalo.com/v0/apps/{appId}/collections/{collectionId}`
* **Update record:** `PUT https://api.adalo.com/v0/apps/{appId}/collections/{collectionId}/{recordId}`

Authenticate using the [API key](/integrations/the-adalo-api.md#to-access-your-adalo-api-key) from the app's API Documentation panel.

#### Prepare the address payload

The shape Adalo expects for a Location field is:

```json
{
  "LocationField": {
    "placeId": "ChIJI0kVGw-jTIcRnXPJXm_cYWk",
    "fullAddress": "123 Main St, Springfield, IL 62701, USA",
    "coordinates": {
      "latitude": 39.7817,
      "longitude": -89.6501
    },
    "addressElements": {
      "address1": "123 Main St",
      "address2": "",
      "city": "Springfield",
      "region": "Illinois",
      "country": "United States",
      "postalCode": "62701"
    }
  }
}
```

Replace `LocationField` with the actual name of the Location property in the collection.

If the source data is already a complete address, map it into this structure and skip to Step 4. If the source data is raw GPS coordinates and a real address needs to be stored, continue to Step 3.

#### Reverse-geocode raw coordinates

When the source data is `{ latitude, longitude }` (for example, from a device sensor, a third-party tracker, or an IoT feed), reverse-geocode the coordinates before calling Adalo:

1. Call Google's Geocoding API (or another provider) with the lat/lng pair.
2. Map the response into the Location object:
   * `placeId` from the result's `place_id`
   * `fullAddress` from `formatted_address`
   * `coordinates` from the original lat/lng (or the geocoder's `geometry.location`)
   * `addressElements` from `address_components` (street number combined with route goes into `address1`, `locality` goes into `city`, `administrative_area_level_1` goes into `region`, and so on)

#### Send the request

POST or PUT the complete Location object to the Collections API endpoint identified in Step 1. The API will store the full object, and the Location field will work correctly across display, filtering, and map components.

#### Alternative path: When a real address is not needed

If only raw coordinate values are needed (for distance math, custom map pins, or passing to an external API), skip the Location property type entirely:

1. Add two Number properties to the collection, named `Latitude` and `Longitude`.
2. Write to them directly through the Collections API:

```json
{ "Latitude": 39.78, "Longitude": -89.65 }
```

## Known Limitations and Gotchas

* **The API does not reverse-geocode inbound writes.** Sending coordinates alone, or any partial version of the address object, gets stored exactly as sent. The Location field will be malformed and will break display, filtering, and any map component that reads from it.
* **Partial writes silently corrupt the field.** There is no validation error returned for an incomplete address object. The write will succeed and the data will appear saved until something tries to read it.
* **All four top-level keys are required.** `placeId`, `fullAddress`, `coordinates`, and `addressElements` must all be present. Missing any one of them counts as a malformed write.
* **Example of a write that will not work:**

  ```json
  {
    "LocationField": { "latitude": 39.7817, "longitude": -89.6501 }
  }
  ```

  This stores exactly that shape and leaves the Location property in a broken state.
* **The Location property is not interchangeable with raw coordinate fields.** When raw coordinates are all that's needed, use two Number columns instead. Forcing a Location property to do that job adds complexity for no benefit.

## Learn More

* [Adalo API documentation](https://help.adalo.com/integrations/the-adalo-api)
* [Google Geocoding API reference](https://developers.google.com/maps/documentation/geocoding/overview)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.adalo.com/integrations/the-adalo-api/updating-a-location-property-via-the-collections-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.