Location

Location attributes model a physical location in the world. We store all location properties (address lines, postcode, country code, etc) on a single attribute value, rather than separate attributes. This means that when working with locations, updates must be atomic—every property must be specified, even if it is null.

You'll find an example of this attribute as primary_location on both person and company objects.

Locations have the following properties:

• line_1 - the first line of the address, e.g. "1 Infinite Loop"
• line_2 - the second line of the address e.g. "Block 1"
• line_3, line_4, same as above
• locality - the town, neighbourhood or area, e.g. "Cupertino"
• region - the state, county, province or region, e.g. "CA"
• postcode - the postal or zip code, e.g. "95014"
• country_code - the ISO 3166-1 alpha-2 country code, e.g. US
• latitude - latitudinal coordinates, e.g. "37.331741"
• longitude - longitudinal coordinates, e.g. "-122.030333"

There are some properties which are not presently shown in the Attio app but are captured by the API—for example, address lines or postcodes.

Reading values

Depending on your use case, there are various properties of a location that might be relevant for you. The API will return the full object as structured data, without attempting to format it:

{
  "active_from": "2023-04-03T15:21:06.447000000Z",
  "active_until": null,
  "created_by_actor": {...},
  "attribute_type": "location",
  "line_1": "1 Infinite Loop",
  "line_2": null,
  "line_3": null,
  "line_4": null,
  "locality": "Cupertino",
  "region": "CA",
  "postcode": "95014",
  "country_code": "US",
  "latitude": "37.331741",
  "longitude": "-122.030333",

}

Writing values

When writing location values, Attio will intelligently parse strings into structured location data.

{
  "primary_location": "1 Infinite Loop, Cupertino, CA, 95014, US"
}

You may also specify each location property explicitly using an object value. When using the object syntax, we require that updates to a location attribute must specify a value for every attribute, even if it is null.

{
  "primary_location": {
    "line_1": "1 Infinite Loop",
    "line_2": null,
    "line_3": null,
    "line_4": null,
    "locality": "Cupertino",
    "region": "CA",
    "postcode": "95014",
    "country_code": "US",
    "latitude": "37.331741",
    "longitude": "-122.030333"
  }
}

Filtering

The properties line_1, line_2, line_3, line_4, locality, region and postcode can all be filtered by $eq, $contains, $starts_with and $ends_with operators.

The property country_code can be filtered by $eq and $starts_with operators.

{
  "filter": {
    "primary_location": {
       "locality": "Cupertino",
       "region": "CA",
       "country_code": "US"
    }
  }
}

{
  "filter": {
    "primary_location": {
      "locality": {
        "$contains": "cuper" /* Case insensitive */
      }
    }
  }
}

It is not currently possible to filter by latitude/longitude.