Create Place
create_placeCreate a new place with names, type, coordinates, and enclosing places; search first to avoid duplicates and build place hierarchies top-down.
Instructions
Create a new place, such as a village, parish or county, with its names, type, coordinates and the larger places that contain it. Search first: no duplicate check is made, and an existing place is changed with update_place. Build hierarchies top-down: enclosedBy takes existing places only, each with optional dates for when the place belonged there, so create the county before its villages. name, nameLang and nameDate make the primary name and alternateNames the historical or other-language ones; an undated primary name hides dated alternate names. Events point here afterwards through placeHandle on create_event or update_event. Returns the new handle and Gramps ID with the stored name, type, coordinates and enclosing places, and next steps; an unknown type or unreadable date is rejected before anything is saved. For several new records that link to each other, such as the people, events, source and citation of one register entry, use create_records instead: one transaction, all created or none. Writes run one at a time and need a Gramps Web account allowed to edit the tree; a locked or rate-limited write fails with the delay to wait before retrying it. Formats of every argument: get_reference(topic: "input-guide").
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude in decimal degrees, north positive (52.2297). Text value. JSON strings are accepted; JSON numbers are also accepted and sent as text. | |
| lon | No | Longitude in decimal degrees, east positive (21.0122). Text value. JSON strings are accepted; JSON numbers are also accepted and sent as text. | |
| code | No | Place code or postal code (optional). | |
| name | Yes | Primary name (required). | |
| nameDate | No | When the primary name applies (default: always). Gramps shows the first name, primary first, whose date is empty or matches the event date, so an undated primary name hides dated alternate names: date the primary name too ("from 1937-02-10"). Dashes are spans; open "1991-" / "from 1991" are From. Unreadable dates are rejected. | |
| nameLang | No | Language code of the primary name, e.g. pl or de (optional). | |
| isPrivate | No | Mark the place private (default false). | |
| placeType | No | Place type, e.g. Country, Province, County, City, Town, Village, Hamlet, Parish. Must be a standard Gramps type or a custom one the tree already uses; anything else is rejected with suggestions. List: get_reference(topic: "types"). | |
| enclosedBy | No | Places that contain this one. Parent place refs via enclosedBy (not enclosedByHandles): handle or Gramps ID, array of them, JSON array of {ref, date?}, or shorthand "HANDLE::1920-1950" (date optional). Place dashes are spans (from…to); open "1991-" / "from 1991" are From. English months OK: "HANDLE::from 1 Oct 1929 to 27 Sep 1937". Examples: [{ref:"…", date:"1708-1927"}], "HANDLE::1991-", date "1703-1914-08-31". Unrecognized dates fail validation. Smaller region → larger region order. See get_reference(topic: "input-guide", section: "dates"). | |
| tagHandles | No | Tags. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| noteHandles | No | Notes. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. | |
| mediaHandles | No | Media. Media handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string. To show only part of an image, such as one record on a page scan, give an object {"ref":"…","region":[left, top, right, bottom]} in place of the handle. A region is [left, top, right, bottom]: its edges in percent of the image width and height, 0 to 100, measured from the top-left corner; [10, 20, 60, 45] runs from 10% to 60% across and from 20% to 45% down. [0, 0, 100, 100] shows the whole image again; read_media with the same region shows what it covers. | |
| alternateNames | No | Other names: historical, other languages. Alternate place names: array of strings ("Old Name" or "Old Name::de"), simple objects {value, lang?, date?}, or JSON array. Dated example: [{value:"New York", date:"1914-08-31-1924-01-26"}] or date "from 5 Jul 1944". Place dashes are spans (from…to); open "1991-" / "from 1991" are From. Unrecognized dates fail validation (see get_reference(topic: "input-guide", section: "dates")). | |
| citationHandles | No | Citations. Handles, not Gramps IDs: JSON array ["h1","h2"], one handle, or a comma/semicolon/newline-separated string; entries may also be objects {"ref":"…"}. |