← All playbooks · Raw API

task-create-location

# Capability: Create a new location (CareDriver market)

## Intent phrases

- create location
- new location page
- new market
- new drive city
- add metro
- launch city page
- new CareDriver city
- create /drive/ city entry

## Requires capabilities

`pages` (locations are not marketing `page` entries — see prerequisites)

## Prerequisites

- Read `cms-edit://customer/location-pages`
- Read `cms-edit://customer/routing` for `/drive/{slug}/` URL rules
- Read `cms-edit://customer/task-media-reuse-and-upload` before new hero images
- Confirm product wants a **new market** (slug, active indexing, copy owners)
- **Do not** create a marketing `page` with slug `drive/…` to fake a location

## Content model reminder

| Item | Value |
|------|--------|
| Contentful type | `location` |
| Public URL | `https://www.hopskipdrive.com/drive/{slug}/` |
| Slug pattern | `{city}-{st}` lowercase, e.g. `denver-co`, `los-angeles-ca` |
| Shared template (typical) | Location page template id `6giibBl8cPHV6rRbTSis2F` |
| Required | `city`, `state`, `template`, `heroImage` |

## Inputs to collect from user

1. City display name  
2. State (as used on site — often full name e.g. `Colorado`, not only `CO`)  
3. URL slug (`{city}-{st}`)  
4. Whether `active` / indexed should be true at launch  
5. SEO title + meta description (or formula approval)  
6. Service areas / cities list for serving section  
7. Hero image (reuse asset or upload)  
8. Optional: laptop/app visuals, `alternativeContents` clones from a reference market  
9. Optional: optimized JobPosting at launch → `task-location-jobposting-schema` (add one market). Hiring-wave date refreshes are that playbook’s **Periodic wave update**, not this task.

## Reference markets (clone patterns)

| Market | When to use as pattern |
|--------|-------------------------|
| `los-angeles-ca` | Large market field patterns |
| `denver-co` | Active mid/large market; uses shared optimized JobPosting + location `meta` |
| Any published mid-size market | Safer clone for hero/SEO tone |

Open a reference with `cms_edit ["open", "--id", "<refLocationId>"]` / peek and copy field formulas — do not invent a new layout stack on a location entry (layout comes from **template** + overrides).

## Steps — create

### A. Prefer automated create when available

1. `cms_edit ["index", "sync"]` if needed for lookups.  
2. Try creating a `location` entry only if the current cms-edit version supports it (`create from-json` with `contentType: location` and required fields, or a dedicated create command).  
3. Always `--dry-run` / strict validation first when using JSON create.  
4. If create is rejected (missing slug/title page shape, unsupported type, etc.), use **path B** — do not fall back to creating a `page`.

### B. Contentful UI or Management API (common today)

1. In Contentful (or CMA script), create entry type **Location**.  
2. Set at minimum:
   - `cmsLabel` / internal name clear for editors  
   - `city`, `state`, `slug`  
   - `template` → shared Location page template (`6giibBl8cPHV6rRbTSis2F` unless product specifies a variant)  
   - `heroImage` → real asset (required)  
   - `active` as agreed  
   - `title`, `description` (SEO)  
   - `cities` / `areas` / `servingHeading` / `servingCopy` as needed  
   - hero/laptop/app overrides mirroring a reference market  
3. Note the new entry **id**.  
4. Continue with cms-edit for draft polish:

```
cms_edit ["open", "--id", "<newLocationId>"]
cms_edit ["read", "@root"]
# set / rtf scalar and rich text overrides
cms_edit ["diff"]
cms_edit ["save"]
```

### C. After fields are correct

1. Preview `/drive/{slug}/` on staging/preview (or production after publish — user decision).  
2. Confirm hero, city tokens, form/apply path, no empty required media.  
3. Human **publish** in Contentful.  
4. Optional: optimized JobPosting → `cms-edit://customer/task-location-jobposting-schema`.  
5. `task-publish-handoff`.

## Field cookbook (typical)

| Field | Guidance |
|-------|----------|
| `title` | CareDriver / gig / city SEO pattern from a reference market |
| `description` | Meta ≤ ~160 chars; city + CareDriver + schedule/pay theme without inventing pay figures unless approved |
| `slug` | Lowercase; unique; matches URL segment only (no `drive/` prefix) |
| `cities` | Short label e.g. `Denver, CO` |
| `areas` | Symbol list of neighborhoods/regions if used site-wide |
| `servingCopy` | Service-area narrative; keep accurate to market |
| `structuredData` | Leave empty at create → template default JobPosting until `task-location-jobposting-schema` (shared schema + location `meta`, not a clone) |

## Confirmation gates

1. User confirms slug, city, state, active/indexed, and template  
2. Hero asset exists (reuse-first)  
3. No fake `page` entry for the market  
4. `diff` before `save` when editing via cms-edit  
5. Publish is human-owned  

## Out of scope

- Publish  
- Global nav / location pickers without product request  
- CareDriver hub `/drive` (`task-audience-hubs`)  
- Blog posts about cities (`articles`)  
- Pushing git production branches  
- Inventing JobPosting HTML without the JobPosting playbook  

## Related resources

- `cms-edit://customer/location-pages`
- `cms-edit://customer/task-location-pages`
- `cms-edit://customer/task-location-jobposting-schema`
- `cms-edit://customer/task-media-reuse-and-upload`
- `cms-edit://customer/task-publish-handoff`
- `cms-edit://customer/audience-hubs` (hub only)