# city.atls.actor.location

> Published by [atls.city](https://lexicon.garden/identity/did:plc:l37i5se642dgeb7kmrdwoqv4)

✓ This is the authoritative definition for this NSID.

## Description

A user's self-declared geographic locations, stored on their PDS. Wraps community.lexicon.location.address for forward compatibility.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:l37i5se642dgeb7kmrdwoqv4/city.atls.actor.location)
- [Documentation](https://lexicon.garden/lexicon/did:plc:l37i5se642dgeb7kmrdwoqv4/city.atls.actor.location/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:l37i5se642dgeb7kmrdwoqv4/city.atls.actor.location/examples)

## Definitions

### `city.atls.actor.location`

**Type**: `record`

Singleton record of the user's location tags.

**Key**: `literal:self`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `locations` | `array` | Yes | The user's tagged locations (max 3). |
| `updatedAt` | `string` (datetime) | Yes | Timestamp of the most recent change. |

### `city.atls.actor.location#osmId`

**Type**: `integer`

Optional OpenStreetMap node/relation ID for the location. Globally unique geographic identifier. See https://www.openstreetmap.org/node/{id} or /relation/{id}

```json
{
  "type": "integer",
  "description": "Optional OpenStreetMap node/relation ID for the location. Globally unique geographic identifier. See https://www.openstreetmap.org/node/{id} or /relation/{id}"
}
```

### `city.atls.actor.location#address`

**Type**: `object`

A physical location (mirrors community.lexicon.location.address).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | `string` | No | Display name of the location. |
| `region` | `string` | No | Administrative region (e.g. state/province). |
| `country` | `string` | Yes | ISO 3166 country code. |
| `locality` | `string` | No | City or town name. |

### `city.atls.actor.location#osmType`

**Type**: `string`

OSM element type: node, way, or relation.

**Known Values**:
- `node`
- `way`
- `relation`

### `city.atls.actor.location#atlasKey`

**Type**: `string`

Optional ATlas canonical location key (e.g. US-OR-Portland). When present, ATlas uses this for exact matching instead of fuzzy text matching. Look up valid keys at https://atls.city/api/locations/lookup

### `city.atls.actor.location#locationEntry`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `osmId` | `ref` → `#osmId` | No |  |
| `addedAt` | `string` (datetime) | No |  |
| `address` | `ref` → `#address` | Yes | Location in community.lexicon.location.address format. |
| `osmType` | `ref` → `#osmType` | No |  |
| `atlasKey` | `ref` → `#atlasKey` | No |  |
| `isPrimary` | `boolean` | Yes | Whether this is the user's primary location. |

## Raw Schema

```json
{
  "id": "city.atls.actor.location",
  "defs": {
    "main": {
      "key": "literal:self",
      "type": "record",
      "record": {
        "type": "object",
        "required": [
          "locations",
          "updatedAt"
        ],
        "properties": {
          "locations": {
            "type": "array",
            "items": {
              "ref": "#locationEntry",
              "type": "ref"
            },
            "maxLength": 3,
            "description": "The user's tagged locations (max 3)."
          },
          "updatedAt": {
            "type": "string",
            "format": "datetime",
            "description": "Timestamp of the most recent change."
          }
        }
      },
      "description": "Singleton record of the user's location tags."
    },
    "osmId": {
      "type": "integer",
      "description": "Optional OpenStreetMap node/relation ID for the location. Globally unique geographic identifier. See https://www.openstreetmap.org/node/{id} or /relation/{id}"
    },
    "address": {
      "type": "object",
      "required": [
        "country"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Display name of the location."
        },
        "region": {
          "type": "string",
          "description": "Administrative region (e.g. state/province)."
        },
        "country": {
          "type": "string",
          "maxLength": 10,
          "minLength": 2,
          "description": "ISO 3166 country code."
        },
        "locality": {
          "type": "string",
          "description": "City or town name."
        }
      },
      "description": "A physical location (mirrors community.lexicon.location.address)."
    },
    "osmType": {
      "type": "string",
      "description": "OSM element type: node, way, or relation.",
      "knownValues": [
        "node",
        "way",
        "relation"
      ]
    },
    "atlasKey": {
      "type": "string",
      "description": "Optional ATlas canonical location key (e.g. US-OR-Portland). When present, ATlas uses this for exact matching instead of fuzzy text matching. Look up valid keys at https://atls.city/api/locations/lookup"
    },
    "locationEntry": {
      "type": "object",
      "required": [
        "address",
        "isPrimary"
      ],
      "properties": {
        "osmId": {
          "ref": "#osmId",
          "type": "ref"
        },
        "addedAt": {
          "type": "string",
          "format": "datetime"
        },
        "address": {
          "ref": "#address",
          "type": "ref",
          "description": "Location in community.lexicon.location.address format."
        },
        "osmType": {
          "ref": "#osmType",
          "type": "ref"
        },
        "atlasKey": {
          "ref": "#atlasKey",
          "type": "ref"
        },
        "isPrimary": {
          "type": "boolean",
          "description": "Whether this is the user's primary location."
        }
      }
    }
  },
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1,
  "description": "A user's self-declared geographic locations, stored on their PDS. Wraps community.lexicon.location.address for forward compatibility."
}
```