place.birds.sighting Documentation (EN)

A bird sighting logged by the observer, stored in their own repository. Honor system: `species` is what the observer believes they saw, not a verified determination.

main record

A bird sighting logged by the observer, stored in their own repository. Honor system: `species` is what the observer believes they saw, not a verified determination.

Record Key tid Timestamp-based ID

Properties

count integer Optional

How many individuals the observer counted. Absent means one, or means they did not count.

minimum: 1maximum: 100000

createdAt string datetime Required

Client-declared timestamp for when this record was written.

location ref #location Optional

Roughly where the bird was. Optional, and deliberately coarse — see #location.

media array of ref #media Optional

Evidence, in whatever form it was captured: a photo, a video, or a recording of the call. Ordered as the observer added it.

maxLength: 4 items

notes string Optional

Anything else the observer wants to say about the sighting: behaviour, plumage, who they were with.

maxLength: 3000 bytesmaxGraphemes: 600 graphemes

observedAt string datetime Required

Client-declared timestamp for when the bird was seen. Distinct from createdAt so a sighting can be written up later. Not verified by anything.

species string Required

Common name as the observer said it. Free text on purpose — always present, even when no code was resolved.

maxLength: 640 bytesmaxGraphemes: 160 graphemes

speciesCode string Optional

The observer's asserted identification as a stable eBird/Clements taxon code (e.g. `norcar`). Present when they picked from the list; absent when they just typed something. May be a `spuh` or `slash` code when the identification is honestly partial.

maxLength: 32 bytes

thumb blob Optional

The image the observer chose to represent this sighting in compact views. Must be either an image in `media` or a `thumb` belonging to an item in `media`; clients should ignore unrelated blobs.

maxSize: 100.0 MB

View raw schema

{
  "key": "tid",
  "type": "record",
  "record": {
    "type": "object",
    "required": [
      "species",
      "observedAt",
      "createdAt"
    ],
    "properties": {
      "count": {
        "type": "integer",
        "maximum": 100000,
        "minimum": 1,
        "description": "How many individuals the observer counted. Absent means one, or means they did not count."
      },
      "media": {
        "type": "array",
        "items": {
          "ref": "#media",
          "type": "ref"
        },
        "maxLength": 4,
        "description": "Evidence, in whatever form it was captured: a photo, a video, or a recording of the call. Ordered as the observer added it."
      },
      "notes": {
        "type": "string",
        "maxLength": 3000,
        "description": "Anything else the observer wants to say about the sighting: behaviour, plumage, who they were with.",
        "maxGraphemes": 600
      },
      "thumb": {
        "type": "blob",
        "accept": [
          "image/*"
        ],
        "maxSize": 100000000,
        "description": "The image the observer chose to represent this sighting in compact views. Must be either an image in `media` or a `thumb` belonging to an item in `media`; clients should ignore unrelated blobs."
      },
      "species": {
        "type": "string",
        "maxLength": 640,
        "description": "Common name as the observer said it. Free text on purpose — always present, even when no code was resolved.",
        "maxGraphemes": 160
      },
      "location": {
        "ref": "#location",
        "type": "ref",
        "description": "Roughly where the bird was. Optional, and deliberately coarse — see #location."
      },
      "createdAt": {
        "type": "string",
        "format": "datetime",
        "description": "Client-declared timestamp for when this record was written."
      },
      "observedAt": {
        "type": "string",
        "format": "datetime",
        "description": "Client-declared timestamp for when the bird was seen. Distinct from createdAt so a sighting can be written up later. Not verified by anything."
      },
      "speciesCode": {
        "type": "string",
        "maxLength": 32,
        "description": "The observer's asserted identification as a stable eBird/Clements taxon code (e.g. `norcar`). Present when they picked from the list; absent when they just typed something. May be a `spuh` or `slash` code when the identification is honestly partial."
      }
    }
  },
  "description": "A bird sighting logged by the observer, stored in their own repository. Honor system: `species` is what the observer believes they saw, not a verified determination."
}

location object

No description available.

Properties

latitude string Required

Decimal degrees, as a string to avoid float drift. Deliberately coarse: clients should write no more than 3 decimal places (~110m). These records are public and permanent, and a bird sighting does not need a precise fix.

maxLength: 32 bytes

longitude string Required

Decimal degrees, as a string. Same precision limit as latitude.

maxLength: 32 bytes

name string Optional

Free-text place name, as the observer chose it (e.g. "Montrose Point Bird Sanctuary, Chicago"). Independent of the coordinates and not verified against them.

maxLength: 640 bytesmaxGraphemes: 160 graphemes

View raw schema

{
  "type": "object",
  "required": [
    "latitude",
    "longitude"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 640,
      "description": "Free-text place name, as the observer chose it (e.g. \"Montrose Point Bird Sanctuary, Chicago\"). Independent of the coordinates and not verified against them.",
      "maxGraphemes": 160
    },
    "latitude": {
      "type": "string",
      "maxLength": 32,
      "description": "Decimal degrees, as a string to avoid float drift. Deliberately coarse: clients should write no more than 3 decimal places (~110m). These records are public and permanent, and a bird sighting does not need a precise fix."
    },
    "longitude": {
      "type": "string",
      "maxLength": 32,
      "description": "Decimal degrees, as a string. Same precision limit as latitude."
    }
  }
}

media object

No description available.

Properties

alt string Optional

Alt text describing the media for people who cannot see or hear it.

maxLength: 2000 bytesmaxGraphemes: 400 graphemes

blob blob Required

The captured file. Audio is first-class here: a bird's call is often better evidence than a photograph of a silhouette.

maxSize: 100.0 MB

thumb blob Optional

A still representing this media — for a video, a frame the observer chose. Derived from `blob`, never captured separately, so a client may regenerate it. Absent for media that is already an image.

maxSize: 2.0 MB

View raw schema

{
  "type": "object",
  "required": [
    "blob"
  ],
  "properties": {
    "alt": {
      "type": "string",
      "maxLength": 2000,
      "description": "Alt text describing the media for people who cannot see or hear it.",
      "maxGraphemes": 400
    },
    "blob": {
      "type": "blob",
      "accept": [
        "image/*",
        "audio/*",
        "video/*"
      ],
      "maxSize": 100000000,
      "description": "The captured file. Audio is first-class here: a bird's call is often better evidence than a photograph of a silhouette."
    },
    "thumb": {
      "type": "blob",
      "accept": [
        "image/jpeg",
        "image/png",
        "image/webp"
      ],
      "maxSize": 2000000,
      "description": "A still representing this media — for a video, a frame the observer chose. Derived from `blob`, never captured separately, so a client may regenerate it. Absent for media that is already an image."
    }
  }
}