NYWalker is not very complicated, but that doesn’t mean it doesn’t need documentation. If you want to know more about the application, please see the “About” page. If you want specific rules for data entry, see “Rules.” This help page is meant only for front-end users. The “Admin” section, at the end, is appropriate for front-end admins.

Getting started

Perhaps you’ve been assigned to use NYWalker to encode a novel or part of a novel in class. That’s great, and we hope you will find the experience interesting, especially once you see the results of your work on a map. There are two things, then, you definitely need before starting up, your login information and your book.

Your professor (or whoever is handling the technical administration of this application) will have provided you with a username and password. Use those to login. If you’ve forgotten either, you’ll have to check with the administrator to reset them for you. Once you log in, you will be taken back to the main page.

Once you are logged in, you should first change your password. You may do so by clicking on your username at the top right of the page. You can also see your contributions there.

Your password changed, you are ready to start working. First you need, of course, the book you will be encoding. Years of experience have suggested that the best way to encode the book is by underlining places mentioned in the text as you read it, and then noting at the top of the page if there are places mentioned or not. This ensures that you don’t lose your notes (unless you lose the book!) and that you can quickly see if there are places mentioned or not. Otherwise, you may get confused or distracted by other underlining, like of key passages.

Do not try to encode a text you have not read. You will make many, many mistakes. This is guaranteed.

Once you’re logged in and you have your book handy, you have to find the book in the list under the Books tab. Any book you have permission to add Instances to will have a big button reading “Add instance” beside it. When you are ready to start, you can click on that button.

Adding Instances

NYWalker is designed to collect three kinds of data: Books, Places, and Instances. Books are added and edited by admins, but you will be adding Instances, and, when necessary, Places.

What is an Instance? It’s the occurrence of a Place in a Book. Every Instance, then, has at least three attributes: a Place, a page number, and the sequence in which it appears. A fourth attribute, the Special Field, is unique to the each Book.

For example, Colum McCann’s 2009 novel Let the Great World Spin opens with these sentences:

Those who saw him hushed. On Church Street. Liberty. Cortlandt. West Street. Fulton. Vesey. It was a silence that heard itself, awful and beautiful. Some thought at first that it must have been a trick of the light, something to do with the weather, an accident of shadowfall. Others figured it might be the perfect city joke.

In just this example, there are references to seven places (six streets and the “city” at the end). Since “city” is a general term, even though we know the narrator means New York City, you won’t make note of it. The six streets, however… They are six Instances of six different Places.

And so you can add your first Instance. Click on that “Add instance” button from earlier, and a form should appear that asks for the “Place.”

If you start typing “Church,” a dropdown menu should appear with a bunch of options that look like this:

Place name - {Some other place name}

One of the rows in the dropdown menu reads “Church Street - {Church Street, NYC},” and that is what you want. The part inside the {}s is the “official” name of the place, and the part at the beginning is a historical name (like “Saigon - {Ho Chi Minh City}”), or a casual name (like “The Big Apple - {New York City}), or simply a variation (like “Fourteenth St. - {14th Street, NYC}”).

The software should automatically copy the historical/casual/alternate name into the second field, labeled “Place name in text.” So you should now have “Church Street - {Church Street, NYC}” in the top field and “Church Street” in the second. You can add a page (3), and, because it’s the first Instance on the page, you put in a 1 for sequence. You can also add a note about the instance and encode it with regarding the parameters of the special field.

Furthermore, the software makes a few assumptions regarding page and sequence. Every new Instance has, at first, the same page as the previous one, with the sequence raised by one. If you change the page number, then the sequence resets to 1.

Data entry is not a lot of fun, so I recommend learning to use the keyboard for most of your work. Use the tab key to move from field to field, the arrow keys to navigate the dropdown menu (and increase the page or sequence, if you need to), and, finally, esc to close the dropdown menu and return to activate one of the buttons. Also, shift + tab moves through the fields backwards. The goal is to limit the amount you use the mouse!

Sometimes, alas, there will be no Place in the dropdown that matches your Instance. That’s when you use the “Add new place” button.

Adding Places

While adding an Instance is relatively easy, adding a Place requires a bit more care. If nothing comes up in the “Place” dropdown that fits, leave your text in that field and type tab to move to the “Add new place” button and hit return to open the “Add new place” popup.

The first field lets you search for your place in the GeoNames gazetteer, a directory for place names. GeoNames works best for anything the size of a town or larger, as well as specific places like universities or even some buildings. It’s a great place to make a first try.

You can click on the “Search gazetteer” button right away or tick either of the two checkboxes (tab to move to them, space to select them) to help narrow your results. The first checkbox shows USA places first (Paris, TX before Paris, France), and the second limits its search to New York City, more or less.

Streets and addresses will typically not work, but it doesn’t hurt to try.

If GeoNames returns search results, they will appear on the right side of the popup. A marker shows up where the first place is found. Zoom out and around to see if it fits. If you click the “Use” button, it will copy over the coordinates, etc., to the left side of the popup. The “Map” button, on the other hand, lets you map the other options. The brief description of the place can help you get a sense of whether you have the right place or not, too.

Once you’ve clicked on “Use” and the data has copied over, make sure you pick a descriptive, unique, and short name for your place. Typically it’s a good idea to add a city name or state abbreviation.

Should nothing match your search, there are basically three routes to go: Wikipedia, Google Maps, and manual entry. Each one has different benefits.

Wikipedia is a good second option if GeoNames provides nothing. You can click on the “Searching Wikipedia” link, and it will take you right to Wikipedia’s search results. Historical places are especially well served by the free encyclopedia.

A place in Wikipedia will typically have a set of coordinates in the top right corner. If you click on those, it will take you to that article’s “GeoHack” page. Carefully copy and paste the latitude and longitude (the decimal numbers at the top just below “WGS84”), and then add a name. When using Wikipedia as a source, I paste the URL of the article into the “Source” field.

Google Maps is typically what you want to use for streets that are more than a few blocks long, as Wikipedia won’t give a precise point, choosing to draw the whole line instead. If you click on the “Searching Google Maps” link, Google Maps will search based on your query and drop a pin.

Google Maps gives the latitude and longitude of the pin in the URL. Typically the URL is of this form:,LONGITUDE,ZOOMz/data…

Again, carefully, copy and paste the latitude and longitude from the address bar into the appropriate fields in the form. Choose a good name, add “Google Maps” as the source, and add the place.

What3Words is what we use for manual entry, when you know where something is on a map but don’t want to deal with copying and pasting. This method works great for subway stations, specific buildings that are not in GeoNames, tiny parks, and the rest. You should still try GeoNames, but What3Words is a good substitute. Using it is easy: you move the map to where the place is, move the cursor over the right place (it should be a cross), and click once. The coordinates and What3Words address should copy over. Now give the place a good name, and you can add this place, too.

With all three of these “manual” methods, the map in the popup should update as you add coordinates, dropping a marker where you typed in the latitude and longitude, so you can check to see if the numbers are correct.

As you can see, adding a Place requires a detail-oriented touch. Luckily, once a place is added, you can reuse it whenever you want to or need to.

Editing and Deleting

Currently, Instances can be edited or deleted if you made them. Places cannot be deleted, but some of their characteristics can be edited. If you need a more brute force intervention, contact your admin.


Sometimes mistakes are made. If you see a mistake, where either an Instance is mis-entered or a Place is all wrong, you can click on the “Flag this” button. A popup will appear, where you can add some text about why you think there is an error, and the admins will be able to fix the problem.


Admins can do everything, including handling Books and Users, which normal users cannot.

Similarly, they can delete any Instance or Place and grant Users permission to add Instances to books. A lot of the admin back-end is currently not implemented, though the security features are.