Updating ODN Entities

The ODN Entities dataset contains a list of all entities in the ODN.

Entity Attributes

Each entity has an id, name, type, and rank.

ID

The id of an entity is a string that identifies it. No two entities may have the same id. Entity IDs may contain only numbers and letters with no punctuation or whitespace.

Census IDs

Many entities use US Census FIPS codes as IDs with the following type prefixes:

• region.nation: 0100000US
• region.region: 0200000US
• region.division: 0300000US
• region.state: 0400000US
• region.county: 0500000US
• region.place: 1600000US
• region.zip_code: 8600000US
• region.msa: 310M200US
• region.township: 0610000US

Name

Each entity has a human-readable name associated with it. This can be any string.

Type

The type of an entity is used to determine whether or not two entities are comparable. There is a hierarchy of entity types with levels in the hierarchy separated by .. For example, all geographical types are grouped under region so the type of a county is region.county.

Rank

The rank of an entity denotes its importance compared to all other entities with the same type. For example, regions are ranked by population. A higher rank means that the entity is more important. Providing a rank is optional but encouraged.

Adding Entities

First, create a local CSV file containing a list of the new entities. For example, if we wanted to add Canada to the ODN:

id,name,type,rank
CA,Canada,region.nation,35100000
CABC,British Columbia,region.province,4631000
...

Update Entities

Append your entity CSV file to the ODN Entities dataset.

Update Relations

If the new entities are hierarchically related to each other, update the ODN Relations dataset. This dataset contains parent-child relations between entities from which sibling relationships can be inferred. It is used for the /related endpoint.

To add Canada as a parent of B.C., we would add the following line to the relations dataset:

parent_id,parent_name,parent_type,parent_rank,child_id,child_name,child_type,child_rank
CA,Canada,region.nation,35100000,CABC,British Columbia,region.province,4631000

Update Geographies

If you added any geographical entities that you want to be able to map, you must find and upload geography files.

Find Shapefiles

First, try to find the highest resolution shapefiles that you can. Currently all data from the Census is that the 1:500,000 scale.

Convert Shapefiles to GeoJSON

Next, transform the source files into GeoJSON. ogr2ogr can help with this.

Note that all geometries in the dataset must be of the same type. If there are different geometry types in one dataset, the Socrata backend will split the dataset into separate layers for each type. For example, the original places dataset contained both Polygon and MultiPolygon types, which caused a significant number of cities to not appear in maps. To fix this convert MultiPolygon features to Polygon. This is a simple fix, there is example code here.

Add References to Entities

Each GeoJSON feature has a properties object that contains data about what the feature represents. The ODN expects each GeoJSON feature to have the following properties:

• id (required): Entity ID.
• name (required): Canonical name of the entity. This will be displayed in maps.
• type (required): Fully qualified geographical type. Many parts of the ODN will accept state in place of region.state, but you must use the full type (region.state) here.
• rank (optional): Types with more than one thousand entities should be ranked so that the ODN can prioritize the entities that are shown to the user. The rank property is an integer where a higher rank denotes a higher priority. Population and land area are suitable values for ranking.

Adding properties to GeoJSON is simple with NodeJS. An example for downloading US places and ZIP codes from the Census can be found here.

Upload

Once the file is properly formatted, upload it to Socrata. The web uploader can handle files below 100mb, and it has a special "Import Geospatial Data" option.

Configure ODN Backend

Verify that the dataset has imported correctly and then get its NBE ID. You can now link the backend to the new geodata.

Add an entry to Constants.GEO_URLS to map the new entity type to its geodata. Make sure to use the fully qualified name of the entity type and a NBE ID.

If you added a rank property, add the entity type to Constants.GEO_RANKED.

Now, you should be able to render maps of the new entity type. Verify your changes locally and create a pull request to merge them into staging.