Skip to content

Latest commit

 

History

History
93 lines (74 loc) · 6.26 KB

map.md

File metadata and controls

93 lines (74 loc) · 6.26 KB

Worksite map

/map shows H-1B, PERM and PWD filings by reported worksite state and metro area (2023 Census CBSAs, metropolitan and micropolitan). Selecting a state zooms into its counties (shaded) and cities (circles); a county zooms to its cities, and a city to the ZIP codes its filings report. The zoom is in the URL (state, county, city), and Esc zooms out one level. Within any level the map can also be dragged to pan and zoomed with the mouse wheel, a trackpad or a pinch (zooming at the pointer), or with the + / − buttons; the reset button returns to the level's view. A drag never selects the place under it. Each employer profile also shows where that employer's filings are located.

Measures

Measure Definition
Filings Cases whose worksite is in the place. Includes withdrawn and denied cases.
Per 100k residents Filings ÷ Vintage 2023 Census population estimate × 100,000. Puerto Rico and other territories have no estimate here.
Median wage Median of the yearly wage: hourly × 2,080, weekly × 52, biweekly × 26, monthly × 12. H-1B and PERM use the lower end of the offered range; PWD uses the determined wage. Values below $10k or above $2M a year are ignored. Medians are interpolated within $2,000 bins and need 10 wages.
Level III–IV share Share of cases with prevailing wage level III or IV, among cases reporting a level I–IV. Needs 10 cases.

Rankings by a rate, median or share only include places with at least 25 (states) or 50 (metros) filings.

Placing a case

  1. Worksite fields per program are listed in backend/services/geo.js (fields).
  2. State: postal code or name, normalized (stateCode).
  3. Metro: the worksite ZIP's ZCTA → the county holding most of its land → the 2023 CBSA. ZIPs without a ZCTA use their three-digit prefix if at least 80% of that prefix's ZCTAs share a CBSA. A metro whose states do not include the reported state is discarded.
  4. Cases without a usable ZIP are placed by worksite city when at least 5 ZIP-bearing cases with that city and state agree on one metro at least 80% of the time. The learned city table is stored per program in map_cities and reused for employer profiles.
  5. Occupation: the first six digits of the SOC code. SOC 2000 and 2010 codes map to their SOC 2018 successor through the O*NET crosswalks; when a code was split, the successor with the most similar title wins (for example 15-1132 and 15-1031 → 15-1252 Software Developers).

Counties and cities

  • County: the worksite ZIP's county (the county holding most of the ZCTA's land; Connecticut uses its 2022 planning regions). Cases without a usable ZIP use their city's learned county.
  • City: the reported worksite city within the state, ignoring case, punctuation, a trailing state ("Austin, TX") and the abbreviations St., Ft. and Mt. (geo.localCityKey).
  • Each city's county, map point and display spelling are learned from its ZIP-bearing cases: the county with most of them, and the weighted median of their ZIP points (2023 ZCTA Gazetteer) within it. Cities never reported with a ZIP are listed but not drawn. The learned table is map_city_index (<program>:<state>).
  • Per-resident rates use Vintage 2023 county estimates; cities have none.
  • GET /api/map/local?program&year&occupation&state returns one state's counties and cities, from map_local. A state with more than 300 rows has its own document (<program>:<year>:<occupation>:<state>); smaller states of a slice share <program>:<year>:<occupation>:*. At most 1,500 cities are listed per state (the rest are counted), and cities with at least 10 filings list their top 10 ZIP codes.
  • County outlines (Census 2023 cartographic boundaries, 1:5,000,000) are one file per state in frontend/src/data/counties/, loaded only when the map zooms into that state.

Refresh

node scripts/refresh-employers.js --map (also part of the nightly CronJob, before --profiles):

  1. For each program, cases are reduced in MongoDB to distinct (ZIP, city, state, year, occupation, level, wage bin) cells, written to map_cells_<program>_tmp.
  2. The city table is learned from those cells.
  3. One pass per published occupation (≥ 50 filings, top 300) and one pass for the rest build map_stats documents keyed <program>:<year|all>:<occupation|all>. Each occupation's cells are read in year order so its county and city detail is written year by year.
  4. County and city detail for all occupations is built in scans of three years at a time.
  5. Stale documents are deleted, map_meta gets the years and occupations, and the temporary collection is dropped.

map_meta.localVersion records the county and city format (LOCAL_VERSION); a program is rebuilt when it differs.

A program is skipped when its case count and search_insights revision are unchanged since the last build; --map-force rebuilds anyway. H-1B (9M+ cases) takes the longest; the temporary collection needs a few hundred MB of disk.

Reference data

backend/data/geo/*.json, frontend/src/data/usStates.json and frontend/src/data/counties/*.json are generated by node backend/scripts/build-geo-data.mjs <source directory>; the script header lists every source URL. Sources: U.S. Census Bureau (2020 ZCTA relationship files, the 2022 Connecticut planning-region file, July 2023 CBSA delineations, 2023 Gazetteer, Vintage 2023 population estimates), us-atlas state shapes, and the O*NET 2010→2019 and 2009→2010 crosswalks (USDOL/ETA, CC BY 4.0).

Case search links

Places link to case search with worksiteState (exact state, matching both postal codes and names). With a state, the worksite text matches the city only. Metro links search the principal city, so suburbs are not included, and search does not filter by occupation.

Status

The administration page's Site data tab (GET /api/admin/site-status) shows the nightly refresh run (current step, latest progress, recent runs and errors, recorded in discovery_state refresh), each program's map build (phase and occupation progress while building, recorded in discovery_state map), and the employer directory, identities, worksite search, insights snapshots and profile caches. A run or build marked running without a live discovery_locks lease is shown as interrupted.