{"id":14063477,"url":"https://github.com/socrata/Socrata-PowerShell","last_synced_at":"2025-07-29T15:33:19.009Z","repository":{"id":66760143,"uuid":"523097098","full_name":"socrata/Socrata-PowerShell","owner":"socrata","description":"PowerShell module for creating and updating datasets on a Socrata domain","archived":false,"fork":false,"pushed_at":"2023-10-24T19:57:16.000Z","size":40,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-12-04T01:33:59.524Z","etag":null,"topics":["engineering","socrata-sdk"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/socrata.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-09T20:20:34.000Z","updated_at":"2024-08-21T22:10:20.000Z","dependencies_parsed_at":"2023-10-24T20:40:10.218Z","dependency_job_id":null,"html_url":"https://github.com/socrata/Socrata-PowerShell","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/socrata/Socrata-PowerShell","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socrata%2FSocrata-PowerShell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socrata%2FSocrata-PowerShell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socrata%2FSocrata-PowerShell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socrata%2FSocrata-PowerShell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/socrata","download_url":"https://codeload.github.com/socrata/Socrata-PowerShell/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socrata%2FSocrata-PowerShell/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267709614,"owners_count":24131922,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["engineering","socrata-sdk"],"created_at":"2024-08-13T07:03:21.592Z","updated_at":"2025-07-29T15:33:18.715Z","avatar_url":"https://github.com/socrata.png","language":"PowerShell","funding_links":[],"categories":["PowerShell"],"sub_categories":[],"readme":"Socrata-PowerShell\n==================\n\nA PowerShell module for creating and updating datasets on a Socrata domain.\n\n## Contents\n\n* [Installation](#installation)\n* [Quickstart](#quickstart)\n* [Authentication](#authentication)\n* [Examples](#examples)\n  + [Update an existing dataset](#update-an-existing-dataset)\n  + [Create a new dataset](#create-a-new-dataset)\n  + [Create a dataset draft](#create-a-dataset-draft)\n  + [Get dataset metadata](#get-dataset-metadata)\n  + [Update dataset metadata](#update-dataset-metadata)\n* [Tests](#tests)\n\n## Installation\n\nThis module requires PowerShell 5.1 or greater. To install, follow these steps:\n\n1. Download this repository [as a ZIP] or `git clone` it locally\n2. Unzip the directory, if necessary\n3. Move the `Socrata-PowerShell` directory to wherever you'd like to keep it\n4. [Import the module] in your PowerShell scripts like so: `Import-Module \"./Socrata-PowerShell/Socrata.psm1\"` (updating the import filepath as needed)\n\nFor detailed information on installing PowerShell modules locally and globally, see [Installing a PowerShell Module].\n\n[as a ZIP]: https://github.com/socrata/Socrata-PowerShell/archive/refs/heads/main.zip\n[Import the module]: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/import-module\n[Installing a PowerShell Module]: https://docs.microsoft.com/en-us/powershell/scripting/developer/module/installing-a-powershell-module\n\n## Quickstart\n\nHere's a script that performs a full replace of an existing dataset using a CSV file:\n\n```powershell\nImport-Module \"./Socrata-PowerShell/Socrata.psm1\"\n\n$Url = Update-Dataset `\n    -Domain \"data.example.gov\" `\n    -DatasetId \"fej7-9vb3\" `\n    -Type \"replace\" `\n    -Filepath \"\\\\treasurer\\financial_data\\budget.csv\" `\n    -ErrorAction \"Stop\"\n\nWrite-Host \"Update complete! See dataset here: $Url\"\n```\n\n## Authentication\n\nTo use this module, you must have access to a Socrata user account with permissions to create and/or update datasets on a Socrata domain.\n\nWhile Socrata APIs will accept a username and password as HTTP Basic Auth credentials, it's best to [generate a pair of API keys] and use those instead.\n\nBy default, this module will automatically look for credentials under the environment variables `SOCRATA_USERNAME` and `SOCRATA_PASSWORD`. However, you can also supply credentials explicitly by passing a `PSCredential` to the `-Credentials` parameter:\n\n```powershell\nImport-Module \"./Socrata-PowerShell/Socrata.psm1\"\n\n$Credentials = New-Object PSCredential(\n    $Env:API_KEY,\n    ($Env:API_SECRET | ConvertTo-SecureString -AsPlainText -Force)\n)\n\nUpdate-Dataset `\n    -Domain \"data.example.gov\" `\n    -DatasetId \"fej7-9vb3\" `\n    -Type \"replace\" `\n    -Filepath \"\\\\treasurer\\financial_data\\budget.csv\" `\n    -Credentials $Credentials\n```\n\nAs a reminder, do not store secure credentials in a script or commit them to version control.\n\n[generate a pair of API keys]: https://support.socrata.com/hc/en-us/articles/360015776014-API-Keys\n\n## Examples\n\n### Update an existing dataset\n\n```powershell\nImport-Module \"./Socrata-PowerShell/Socrata.psm1\"\n\nUpdate-Dataset `\n    -Domain \"data.example.gov\" `                   # Required\n    -DatasetId \"c2xb-y8f6\" `                       # Required\n    -Type \"update\" `                               # Required; \"update\" (upsert/append), \"replace\" (full replace), or \"delete\" (delete rows)\n    -Filepath \"C:\\Documents\\vet_facils.geojson\" `  # Required\n    -Filetype \"geojson\" `                          # Optional; if not supplied, this is guessed from the filepath\n    -Publish $true `                               # Optional; $true or $false (default: $true)\n    -Credentials $Credentials                      # Optional; if not supplied, this is looked up from the env variables SOCRATA_USERNAME and SOCRATA_PASSWORD\n```\n\n### Create a new dataset\n\nNote: it's common to run into schema errors and data quality issues when first creating a Socrata dataset programmatically. A better approach is to create a new dataset using the [Data Management Experience] user interface, implement any desired fixes or schema changes, then publish. After that, you can schedule programmatic [updates] for the dataset going forward. However, in cases where dataset creation must be automated, `New-Dataset` may be useful:\n\n[Data Management Experience]: https://support.socrata.com/hc/en-us/articles/115016067067-Using-the-Socrata-Data-Management-Experience\n[updates]: #update-an-existing-dataset\n\n```powershell\nImport-Module \"./Socrata-PowerShell/Socrata.psm1\"\n\nNew-Dataset `\n    -Domain \"data.example.gov\" `                   # Required\n    -Name \"Hospital Bed Availability by County\" `  # Required\n    -Filepath \"\\\\datasets\\BEDS_AVAIL.xlsx\" `       # Required\n    -Filetype \"xlsx\" `                             # Optional; if not supplied, this is guessed from the filepath\n    -Audience \"private\" `                          # Optional; \"private\" or \"public\" (default: \"private\")\n    -Publish $true `                               # Optional; $true or $false (default: $true)\n    -Credentials $Credentials                      # Optional; if not supplied, this is looked up from the env variables SOCRATA_USERNAME and SOCRATA_PASSWORD\n```\n\n### Create a dataset draft\n\nSometimes it's necessary to create a draft revision of a new or existing dataset without publishing the draft. `Update-Dataset` and `New-Dataset` both accept an optional `-Publish` parameter that, when set to `$false`, will leave the revision in draft (unpublished) state.\n\n```powershell\nImport-Module \"./Socrata-PowerShell/Socrata.psm1\"\n\nNew-Dataset `\n    -Domain \"data.example.gov\" `                   # Required\n    -Name \"Assisted Living Facilities by State\" `  # Required\n    -Filepath \"datasets\\assisted_living.csv\" `     # Required\n    -Publish $false                                # Optional; $true or $false (default: $true)\n```\n\n### Get dataset metadata\n\n```powershell\nImport-Module \"./Socrata-PowerShell/Socrata.psm1\"\n\nGet-Metadata `\n    -Domain \"data.example.gov\" `                   # Required\n    -DatasetId \"prx6-94ku\" `                       # Required\n    -Credentials $Credentials                      # Optional; if not supplied, this is looked up from the env variables SOCRATA_USERNAME and SOCRATA_PASSWORD\n```\n\nThis will return an object like the following:\n\n```powershell\n@{\n    id              = \"prx6-94ku\"\n    name            = \"Gross Domestic Product by County, 2021\"\n    attribution     = \"Bureau of Economic Analysis (BEA)\"\n    # ...\n    customFields    = @{\n        Department  = @{\n            Name    = \"Economic Development\"\n            Office  = \"Office of Data and Performance\"\n        }\n    }\n    tags            = @( \"economic\", \"performance\", \"gdp\", \"counties\" )\n}\n```\n\n### Update dataset metadata\n\n```powershell\nImport-Module \"./Socrata-PowerShell/Socrata.psm1\"\n\n$Fields = @{\n    description    = \"An estimate of the value of goods and services by county.\"\n    category       = \"Economy\"\n    customFields   = @{\n        Department = @{\n            Team   = \"Innovation and Analytics Team\"\n        }\n    }\n}\n\nUpdate-Metadata `\n    -Domain \"data.example.gov\" `                   # Required\n    -DatasetId \"prx6-94ku\" `                       # Required\n    -Fields $Fields `                              # Required; must be a hashtable containing metadata fields as key-value pairs\n    -ValidateOnly $false `                         # Optional; $true or $false (default: $false)\n    -Strict $false `                               # Optional; $true or $false (default: $false)\n    -Credentials $Credentials                      # Optional; if not supplied, this is looked up from the env variables SOCRATA_USERNAME and SOCRATA_PASSWORD\n```\n\n## Tests\n\nTo run Socrata-PowerShell's integration tests, run [Pester] at the repository root:\n\n```powershell\nInvoke-Pester -Output \"Detailed\"\n```\n\nFor the tests to pass, the following environment variables must be set:\n\n* `SOCRATA_POWERSHELL_TEST_DOMAIN`\n* `SOCRATA_POWERSHELL_TEST_DATASET_ID`\n* `SOCRATA_USERNAME`\n* `SOCRATA_PASSWORD`\n\nTo run script analysis, use [PSScriptAnalyzer]:\n\n```powershell\nInvoke-ScriptAnalyzer -Path \"./Socrata.psm1\"\n```\n\n[Pester]: https://pester.dev\n[PSScriptAnalyzer]: https://learn.microsoft.com/en-us/powershell/module/psscriptanalyzer/?view=ps-modules\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsocrata%2FSocrata-PowerShell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsocrata%2FSocrata-PowerShell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsocrata%2FSocrata-PowerShell/lists"}