Adding and Editing Locations

Exhibit A: When you first go to add a location to a box,
you'll see a page like this one.

I've been meaning to post about this ever since that Big Update, but I kept making tweaks and changes and didn't want to post a long explanation then have the information change a few days later. It seems stable enough now, however, and I don't expect any significant changes in the near future anymore. So, at long last, here's a little information about adding and editing locations.

First, I'd like to note that these instructions apply anywhere you can add or edit locations, whether it's letterbox locations, event locations, virtual locations. Whether it's a custom location for yourself that can override the owner's listed location or whether you're listing the locations that others will see--all of this revolves around the same core piece of code, so they all work identically. Since the vast majority of locations are associated with letterboxes, however, I'll refer to those. Just know that this information applies to events and virtuals as well.

Now, let's take a look at Exhibit A. That's the kind of page you'll see when you first have to enter a location. Ours is empty since we have yet to add any location information, but we'll fix that. The important thing to remember about this page is that it's the geocoder page. A geocoder, to refresh your memory, is a system that converts an address or other human-readable location into latitude and longitude coordinates. Anything you type in here will be run through one or more geocoders in an attempt to figure out precisely where your location is.

Exhibit B: Let the geocoder chew on Seattle, WA.

Also note the small question mark in the blue circle next to the word 'Location.' Whenever you see that icon, clicking on it will take you a relevant entry in the help pages of Atlas Quest. If you're not sure about something, that's always a good thing to check.

So let's type in a location. Because I live in Seattle, we'll use that, and I type in "seattle, wa" because I'm too lazy to capitalize properly. =)

When I click 'Store', the text is sent to one or more geocoders, and it returns the following results:

Exhibit C: The geocoder results.

Now this is pretty darned cool! (At least I think so!) The geocoder found one result that it believes matches your location--a town called Seattle, located in King County, in Washington state, which is located in the United States, and even plots a map marking the location so you can verify it's latitude and longitude coordinates.

This is the best case scenario. It's exactly what we wanted, and we can click the 'Next Page' button and continue adding details about our box.

Unfortunately, the results aren't always this clean. Sometimes, the geocoders might find more than one location that appears to match your location. For instance, if we try searching for the location named "Portland", we'll get these results:

Exhibit D: Wow, there certainly are a lot of Portlands out there!

The geocoder returned seven possible matches! This isn't even the complete list of Portlands--these are just the ones that the geocoder thinks are the most likely ones that you are referring to, sorted roughly in order of size from largest to smallest under the assumption that you probably are referring to one of the largest Portlands.

In this case, Portland, Oregon, gets first billing, and Portland, Maine, gets the second billing. Those two are also the two that most people can name right off the top of their heads, so it's nice to see that the geocoder gave those two the two top slots.

The numbers in the list correspond with the numbered markers on the map, so we can easily see their relative locations. Assuming we wanted to use the Portland in Maine, we can get there either by adding Maine to the text box to narrow down the result, or by clicking the second item in the list. I click the second item on the list then "Store," and wind up with this view:

Exhibit E: Portland, Maine--there you are!

This is great--we're right where we want to be and it's time to move on to the next page of listing our letterboxing.

That was mostly a contrived example--I knew that there were a lot of Portlands and could force that "error" to happen. Here's a real example that I fell into purely by accident:

Exhibit F: A real-life scenario of multiple matches when I tried entering a location for "cerro san luis, san luis obispo, ca."

When I tried this search, the geocoders came back with three possible matches, all of which are located in the city of San Luis Obispo. Looking at the map, I can clearly tell that the one I was looking for--a prominent and popular mountain in town to hike up--is the #2 option. My search was for "Cerro San Luis," but the official name of the mountain is Cerro San Luis Obispo. My bad--I typed it in wrong. We do that a lot around here--shorten San Luis Obispo to San Luis. The geocoder also found an apartment complex on the Cal Poly campus named Cerro San Luis, though, as well as a street in town named San Luis Drive. I wanted the mountain, however, so clicked on the second option and continued with the listing. All is well! =)

When Geocoders Fail

The worst situation is when the geocoders can't figure out your location at all. Take a look below at Exhibit G.

Exhibit G: The geocoder failed to find our location

In this case, I tried entering a location for "madonna mountain, san luis obispo, ca." The geocoder, however, was unable to find this. There's a good reason that the geocoder can't find this location--officially, it doesn't exist. Madonna Mountain is a name that many locals use to refer to Cerro San Luis Obispo. In fact, most people call it Madonna Mountain. There's a giant M on the mountain (which many people assume is for Madonna, but it's actually short for Mission), and the mountain has been owned by the Madonna family for decades and decades. (No relation to the pop singer.) SLO is famous for the world-famous Madonna Inn, along Madonna Road, right next to the Madonna Inn, and with a giant M on the mountain, it's understandable that people would tend to call it Madonna Mountain. BUT--officially--that's not the name. (After the owner, Alex Madonna, died a few years ago, there was talk about making that name official, but so far, nothing has come from it.)

The only time you usually see Cerro San Luis Obispo (or Cerro San Luis) used is in newspapers and other media that like to be officially correct in such matters.

But long story short, the geocoders were unable to figure out where Madonna Mountain was located because it officially doesn't exist. AQ was able to match the city where you said the mountain was located, and it gives you that as an option, but if you want to pin-point the location better than that, you have two choices:

1. Use the official name of Cerro San Luis Obispo (assuming you knew that to begin with, though, why didn't you just use that as the location?)
2. Create a custom location

We already reviewed how to add Cerro San Luis Obispo as a location, so let's add Madonna Mountain as a custom location this time. =)

Adding Custom Locations

To get out from under the geocoders, which clearly have no idea what Madonna Mountain is, click that "Edit Custom Location" link at the bottom of the list. That's your 'escape hatch' from the geocoders. I click it, which takes us to Exhibit H:

Exhibit H: We've escaped the geocoders into the Custom Location page

The custom location has already been pre-filled with information from Exhibit G. In this case, it's information about the city of San Luis Obispo. A lot of the information will be the same for Madonna Mountain because it's in the city, but we do have to tweak this information specifically for Madonna Mountain.

Most of this page is self-explanatory. The name of the location we want to add is "Madonna Mountain," so we enter that as the "Park Name, Business Name, Etc." section. I don't have an address for that mountain, so I'll leave that blank. (If you know the address for the trailhead, however, it might be a good thing to include.) The city, county, state, and country area already correct, so I'll leave them be.

The coordinates are pretty straight-forward. The peak of Madonna Mountain, which I can look up from Google Maps, is at 35.282741024156, -120.68038151502. (If you have a GPS, you could also have recorded this information when you planted the letterbox.)

Then there's the radius. This is entirely new since the update. AQ now tracks the relative sizes of a given location. A park is usually much smaller than a city, and a city is usually much smaller than a state, and a state is usually much smaller than a country, and now AQ knows this! Which is very useful information for providing accurate search results.

There's a lot of information about the radius if you click the 'help' link for radius, but in a nutshell, it's the distance from the center point of your location to the outer edge of your location, as the crow flies. Assuming your preferences are set to use miles, the distance is in miles. (If your preferences are set for kilometers, you'll have to enter kilometers instead.) The only way to figure this out is to pull out a map--real or online--and measure the distance. For Madonna Mountain, the radius is 0.681 miles.

Exhibit I: Adding a custom location

When I'm done, I click 'Store', and AQ takes me back to the geocoder page, displaying my custom location:

Exhibit J: Madonna Mountain, our custom location, now supported by the geocoders.

And we're on our merry way again.

Adding a custom location can be a bit of a pain--figuring out the coordinates and radius and all that--and if you can make a location work without it, it'll save you a lot of extra effort.

And that's it for now. There's a lot more I want to talk about on that custom location page, but I'll save that for another day.....

Newest Traditional Boxes Widget

I took a break from fixing bugs from the Big Update--the worst of the bugs seem to have been fixed, but there are still a few issues I'm working out. So anyhow, I felt like taking a break from that part of AQ and decided to work on something a bit less ambitious.

You might have noticed that the Big Update tweaked the newest traditional letterboxes widget a bit--the full address of the locations started displaying rather than just the city. This was actually accidental. The update pretty much affected everything that touched traditional boxes. Anywhere and everywhere, if you saw the name of a letterbox someone listed on Atlas Quest, that code would have broke without any modifications, and the widgets were no exception. I fixed this particular widget, after doing a global search for a key function that I used to display locations, and replaced it with the new function call. In this case, however, I thoughtlessly typed the new function as "Display" instead of "DisplayCity." The difference being that the Display() function displays the full address of a location with the DisplayCity() function only displays the city portion of the address. It's a minor bug, as far as bugs go, and I rather liked it since it let me see what people trying as locations and spotting possible bugs in the listing of boxes, so I didn't fix it.

Wassa noticed that and suggested making that an option in the preferences and I thought, "Yeah, I can do that." So I did. =)

And while I was at it, I also added the option to specify a location that the widget will return new box listings for. Would you prefer the widget only show all newly listed letterboxes in Oregon? Done! Would you prefer to see all newly listed boxes within 50 miles of Seattle? Done! What about all newly listed letterboxes along I-5 between Sacramento and Portland? Done! That last one is pretty cool, don't you think? =) Any search that works on the Advanced Search page will work here as well. I doubt most people would have a need for a list of new boxes along a particular route, but the option is there. That's part of the flexibility this update provided--in the code, I just tell AQ to display and process a "location," and it can process any type of location. That box works exact the same, whether it's on the Advanced Search page or the newest boxes widget or from an app or anywhere!

Cool stuff. *nodding*

So go ahead and update your newest traditional boxes widget to suit your preferences. =)

Happy trails!

World Travelers!

I'm still making some tweaks and updates to the geocoders and fixing things that I broke with this big update--yes, there are still outstanding issues that need my attention!--however, the seriousness of them seems to be subsiding. Progress is progress--I'll take it! =)

So I'm still not quite ready to blog about the tip, tricks, and traps to avoid in listing locations with your letterboxes, but it seems a lot of you are figuring it out already.

This morning, I pulled up a map of the most recently listed letterboxes on Atlas Quest. I was actually testing for a certain problem that was reported to me and any search results would have worked for my purposes, but there was that handy, fat little Map Newest Letterboxes button so I made use of it--and was a little surprised to see letterboxes all over the world! Yes, I know, people plant letterboxes all over the world, but usually when I look at that map, I see a bunch of letterboxes listed in the United States and maybe--sometimes--there might be one in Europe or New Zealand or something off the beaten path.

Since the list of newest boxes is always changing, I did a screen shot of the map I saw so you can see what I mean:

Look at that--there are boxes in the United Kingdom, a few in Western Europe, one in the Carribean, one "floating" off the coast of Africa, one in Thailand, a bunch in Alaska, and G--from this point of view--appears to be the Lost City of Atlantis. =)

The Alaska ones, in hindsight, make a lot of sense. There was a letterbox cruise to Alaska recently, and it appears they've been busy listing their letterboxing! That green marker labeled "M" I knew immediately were mystery boxes located "somewhere in the world." World-wide mysteries are mapped to the coordinates at 0, 0, and "M" is at 0, 0. Being a green marker, as I discussed yesterday, floating in the middle of water was nothing unusual and most likely, those mystery boxes are really located in the United States somewhere.

But still, it seemed like an unusual number of boxes are located outside of the United States, and I started worrying if there was a problem with the geocoders putting boxes in the wrong locations, so I took a closer look at the others.

And they're totally legit! Even that blue one mysterious floating in the middle in the Indian Ocean. If you zoomed in close enough, you'd see that it marked the location of a small island that's a part of the British Indian Ocean Territory. Those in Western Europe really are located in Spain, Morocco, and Scotland. The box listed as being in Thailand really is in Vietnam--the map is actually correct, but we're zoomed out so far that Vietnam doesn't show up as a separate country in this view. If you zoomed in, though, it would accurately show the marker in Vietnam. And that marker in the Caribbean Sea--it's hard to tell which island its on from such a zoomed-out view, but when I zoomed in, I could see it was Puerto Rico.

Totally cool!

I also scrolled through the list to note all of the green markers--the green markers, if you remember from yesterday, mean that the location of the box could be "more than 30 miles away" from that specific point. Locations such as a "world-wide mystery," that's to be expected. =) So while a green marker doesn't mean something is wrong, I don't really expect there to be a lot of them either. Most boxes aren't mysteries, after all. There aren't a lot of green markers, but I figured it didn't hurt for me to scroll through the list and double-check that they really are mysteries and therefore should be green.

A mystery box in Maine--check! "The Adirondacks"--check! And oooh..... that's an interesting one, isn't it? Not a state, but the Adirondacks covers a pretty large area that's probably larger than some states. That's the kind of mystery box that the old version of AQ wouldn't have been able to handle gracefully. And a mystery box in West Virginia. Check! And a box in  Juneau, Alaska. Hmm.... Mystery boxes "somewhere in a city" usually should have a red marker, not a green one. I better check that one....

A little Google-sleuthing shows the "City and Borough" of Juneau has an area covering 3,255.0 square miles--that's huge! That fills a circle with a radius of 70 miles--considerably greater than the 30-mile threshold for a green marker. But intuitively, a 70-miles wide circle around Juneau didn't feel right. That must include the entire borough, but what about the city. I ran the location through a couple different geocoders, all of which returned something close to 70 miles as a radius, except one that returned 36 miles. Not sure where that geocoder pulled that number from, but I liked it, and changed the radius to 36 miles. =) Which is still large enough to justify the green marker, but at least it will show up in a location-based search that defaults to 50 miles while the old radius did not.


Yep, they were all supposed to be green markers.
Totally awesome! *nodding* =)

Nothing new to report today, though. Not yet....

The Magic of Geocoders....

Wassa might start fires *cough*LbCon*cough*, but Wassa Jr likes
to help Smokey the Bear prevent forest fires. =)

I was going to spend today explaining the ins and outs of listing a location with your box, but I'm still making tweaks to that code and don't really want to put anything in writing that might change. Maybe by tomorrow I'll be ready for that ball of ear wax. =)

So today will be an easy lesson on geocoders. I've mentioned them in past posts, but I haven't really delved into detail about what they can do that they weren't able to do before this update.

A geocoder, as a reminder, is a system that can convert a human-readable address such as "Lincoln Park, Seattle, WA" into latitude and longitude coordinates that Atlas Quest can use to calculate distances and map locations.

In the "old days" (i.e. a week ago), there was one geocoder. It was the geocoder provided our friends at Google. It wasn't perfect (no geocoder is perfect), but it was leaps better than nothing at all, which is what AQ had been using before the Google geocoder came along.

When I started working on the custom location feature, I discovered the the geocoder AQ had been using was depreciated and replace with a new (and presumably better) geocoder. I needed to upgrade, and the code was not particularly well suited for upgrading the geocoder. I imagined the geocoder as something like a lego piece, and I could snap off the old geocoder and snap on a new geocoder that would fit perfectly into the newly opened space where the old geocoder used to rest.

But it wouldn't be that easy. No, it was going to get messy, but it really shouldn't have been messy had I designed it better. It should work like interchangeable lego pieces.

So, I needed  a replacement for the geocoder, and I started looking around. The replacement geocoder from Google I took a look at, and the results frightened me. It looked mean and ugly. So I took a look at the Yahoo geocoder, and with a little poking and prodding, I thought, "Wow, this is cool!" I started working on a Yahoo geocoder, which also returned the radius of a location--a new piece of data AQ never had access to before and I ended up using extensively during the rewrite of the search engine.

The Yahoo geocoder could do some things the old Google geocoder could not--for instance, airport codes. Type in SBP (the airport code for our little local airport in San Luis Obispo), and by golly, it finds that airport and returns all of the relevant entries. Not that it would be used very often, but still, it's nice when you realize there's more functionality than before.

More useful, perhaps, was that it could geocode locations in a huge list of foreign countries--here's a list I've copied from their documentation:

North and South America:

• BAHAMAS, THE
• BRAZIL
• CANADA
• CAYMAN ISLANDS
• FRENCH GUIANA
• GUADALOUPE
• MARTINIQUE
• MEXICO
• SAINT BARTHELEMY
• USA (including PUERTO RICO and US VIRGIN ISLANDS)

Europe:

• ALBANIA
• ANDORRA
• AUSTRIA
• BELARUS
• BELGIUM
• BOSNIA AND HERZEGOVINA
• BULGARIA
• CROATIA
• CZECH REPUBLIC
• DENMARK
• ESTONIA
• FINLAND
• FRANCE
• GERMANY
• GIBRALTAR
• GREECE
• HUNGARY
• ICELAND
• IRELAND
• ITALY
• LATVIA
• LIECHTENSTEIN
• LITHUANIA
• LUXEMBOURG
• MACEDONIA
• MOLDOVA
• MONACO
• MONTENEGRO
• NETHERLANDS
• NORWAY
• POLAND
• PORTUGAL
• ROMANIA
• RUSSIA
• SAN MARINO
• SERBIA
• SLOVAKIA
• SLOVENIA
• SPAIN
• SWEDEN
• SWITZERLAND
• TURKEY
• UKRAINE
• UNITED KINGDOM (including ISLE of MAN and CHANNEL ISLANDS)
• VATICAN CITY

Asia:

• HONG KONG-CHINA
• INDIA
• INDONESIA
• MACAU-CHINA
• SINGAPORE
• TAIWAN
• THAILAND

Middle-East and Africa:

• BAHRAIN
• BOTSWANA
• EGYPT
• JORDAN
• KENYA
• KUWAIT
• LEBANON
• LESOTHO
• MOROCCO
• MOZAMBIQUE
• NAMIBIA
• NIGERIA
• OMAN
• QATAR
• REUNION
• SAUDI ARABIA
• SOUTH AFRICA
• SWAZILAND
• UNITED ARAB EMIRATES

Holy jumping junipers! That's an awfully big list! (Clearly written by a developer, I might add--a professional writer would have never used all caps in creating such a list!) Not that Liechtenstein and Mozazmbique are letterboxing hotbeds of activity, but still, it's nice to know that the geocoder can figure out such locations! 

I developed a little block of code that used the Yahoo geocoder, got it working, and all was well. I really wanted that "lego-like" snap-in kind of functionality, though, and I figured the best way to do that was to create another geocoder and try snapping it in. I went back and implemented Google's new geocoder, finally getting that to work--and with just a single line of code that was changed, I could switch between the two geocoders practically on the fly. And then I had another idea... why not chain them together into another "super" geocoder? 

In the end, this super-geocoder will attempt to pull in information from three different sources in an attempt to understand your location. Park names that never worked before suddenly were now supported. The Yahoo geocoder supported airport codes, but the Google geocoder did not. The Google geocoder could figure out street intersections, but the Yahoo geocoder didn't seem to be able to do that. Ying and yang. For best results, I needed both.


As it stands now, when you type in a location that AQ need to convert into latitude and longitude coordinates, it runs the information through up to five distinctly different geocoders:

1. The first geocoder really isn't a "geocoder" in the traditional sense. It takes what you typed in and tries to figure out if you're typing in the coordinates directly, so you can run a search for "34.6, 121.6" and have it return boxes near that point.
2. AQ gets the first shot at figuring out what you are trying to say. It'll search it's own database looking for information matching what you typed in, and if it finds it, that's what gets returned.
3. If AQ doesn't find a suitable match, Yahoo gets the next crack at figuring out your request. If a suitable match is found, awesome--that's what AQ will use.
4. When the Yahoo geocoder fails, then the Google geocoder gets a crack at the information. If you ever run a search for a street intersection, it'll almost certainly reach this geocoder. AQ knows only a tiny number of street intersections that people have used for their box locations and Yahoo doesn't seem to handle intersections at all. If a suitable match is found--awesome, AQ runs with it.
5. And finally, if all else fails, there's another source of data I found with 1.86 million "points of interest" in the United States. I found it a little scary some of the small parks I searched for that this source of information could find. Had I bet money, I'd have lost. This data is actually hosted by AQ--the data was in an enormous file and wasn't provided as an API by another company. (I basically had to create the API to use this data--a geocoder that was able to search this file.)

Each of the geocoders has their strengths and weaknesses, but collectively, it's a pretty amazing little beast. If you had trouble listing a certain park as a location in the past, it might work just fine now. The new geocoders, I noticed, also had better support for geographical features, so you can even list boxes as being on specific mountains or by a lake. They also often support more "vague" locations such as "Pacific Northwest" and "Central Coast of California"--perhaps useful for listing mystery boxes in those locations, though admittedly less so for running a search.

I also updated the ability to process coordinates. You can type in a location such as "34.6, 121.6" to run a location-based search centered on that point on the Earth, but AQ is better about processing other formats for the coordinates. It used to be required that you used the latitude, a space, then the longitude. And heaven forbid, don't even THINK about putting the comma between the two! AQ, in the past, was a very temperamental beast.=)

The new "coordinate geocoder" will allow commas now. In fact, you can type in a wide variety of formats that will properly be understood including:

• 50.3 -120.5
• 50.3, -120.5
• -120.5 50.3
• 50.3N 120.5W
• 120.5 W 50.3 N
• 50 18 0 -120 30 0
• 50 18 0N 120 30 0 W
• 50° 18' 0" N 120° 30' 0" W

Ironically, I copied these examples from the "reverse geocoder" directions from the Yahoo geocoder which will convert coordinates into an address. I don't use Yahoo's reverse geocoder, though--I just want to figure out if a person is trying to type in coordinates and understand what they typed in--I don't need to attach an address to it. But all of these examples work with AQ now. I didn't know where these example coordinates went to, but I copied them into AQ to test they really did work, and was pleased to see that they found boxes at Manning Park, Canada! Which is a small park that most people never would have even heard of.... except that it's also the end of the Pacific Crest Trail! Makes me wonder if the person who wrote that documentation on Yahoo's website might have been a former thru-hiker? =)

Before the update went live, I had to run every single location for every single letterbox and event through the new geocoders. Old locations did have have information about the radius of the location, all US locations had no information about the county of the location, and all mystery boxes had no latitude and longitude coordinates associated with them, and for this upgrade, I needed to fill in those blanks. So every single location was run through the geocoder--a process that took the better part of a month--and which is why you might have noticed that the location you had listed for some boxes might have shifted a bit. Most of the issues I found involved the "free-flowing" nature allowed for mystery boxes, so if there's a problem with how one of your boxes got geocoded, the mystery boxes would be the first ones you should check. I tried to fix problematic "updates" manually, but with over 100,000 boxes listed on AQ, manually checking every single one wasn't possible. I wrote a bunch of code for me to help identify "possible problems"--such as a new location that ends up being 6,123 miles away from the coordinates of the old location or a location with a radius of 1000 miles (not many places span such a wide area, but they do exist!). Subtler problems, however, could have slipped through, so it wouldn't hurt to run through your plants and check that the locations are what you think they should be.

So that's the skinny on using the new geocoder. It's bigger, it's better, and badder (in a good way) than ever! =) However, I'll note, there's no such thing as a perfect geocoder--you'll still find locations that none of the geocoders can figure out. But with this update, I hope you'll have a much more difficult time finding "unsupported" locations. =) (And, yes, you CAN use commas in coordinates now!)

Mystery Letterboxes

Please review the emergency instructions
on the brochures in the seat-back pocket
in front of you. You may experience
turbulence, but we'll get you through it!

Believe it or not, I still have more information I'd like to share about the Big Update earlier this week. Today's discussion will focus on mystery letterboxes. I've already talked a little about them in the context of counties, but there is a lot more to them than merely being able to specify a county. =)

If you've run some searches on Atlas Quest, you might have noticed that for the first time, mystery boxes will be included in a location-based search, and that's why you'll always see the "Mystery Boxes" attribute available on the Advanced Search page. Any search you do could possibly return mystery boxes including trip planner searches and location-based searches. So let's run a search for all mystery boxes within 150 miles of Providence, RI.

You might be wondering.... how can AQ possibly calculate the distance to a mystery box--it's a mystery, after all! Rhode Island, as you all might be aware, is a pretty small state. All mystery boxes located "somewhere within Rhode Island" are going to be within 150 miles of Providence because there are no locations still in Rhode Island that are further away than 150 miles. AQ might not know the precise distance of the letterbox, but it knows that all Rhode Island mystery boxes are within 150 miles of Providence. It's impossible for it not to be. =)

Previously, we knew this intuitively, but AQ didn't have the ability to figure this sort of thing out on it's own. This update changes that. Now, every single location AQ knows about has a latitude and longitude coordinate and it has a radius. Rhode Island is listed with a radius of 40.39 miles centered around 41.582584, -71.503414. Obviously, Rhode Island isn't a circle, but these numbers are good enough for an approximation, and when we're talking about mystery boxes, approximations are usually plenty fine. Being approximately correct is better than being precisely wrong. =)

Now, when you run a search for all boxes within 150 miles of Providence, Rhode Island, AQ calculates the distance in two steps. First, it calculates the exact distance--as the crow flies--from the center point of Providence (41.823856, -71.411741) to the center point of the letterbox (41.582584, -71.503414 for Rhode Island mysteries), which comes out to 17.31 miles. So the "average" Rhode Island mystery box is expected to be about 17.31 miles from the city center of Providence. But the thing is, the actual box location could be a lot further away than that. In a worst case scenario, the mystery box might be out the very outer edge if the mystery area, on the other side of the center point for the state: In other words: 17.31 miles + 40.39 miles = 57.7 miles away.

That is--roughly speaking--the worst case scenario for a Rhode Island mystery box if you're in downtown Providence, and that's the distance AQ uses for sorting boxes based on distance. You'd have to run a location-based search that extends at least 58 miles to include Rhode Island mystery boxes, but it will show up.

If you take a look at the results of our search, the first Rhode Island mystery boxes that show up in slot #7 (for me, at least--depending on restrictions, plants, custom locations, etc., your list could be a bit different than mine). Two other types of mystery boxes slip in as being slightly closer to Providence than those that are "somewhere in Rhode Island": county mystery boxes.

A couple of RI boxes are listed as being "somewhere in Providence County" and a few more are listed as being "somewhere in Windham County." Providence is in Providence County, so we know a mystery box in Providence County will be closer than mystery boxes in any other county of Rhode Island, and with an average radius of 16.65 miles, AQ figures that mystery a box "somewhere in Providence County" has a worst-case scenario of 24.9 miles from the center center of Providence.

And similarly, AQ calculation a worst-case scenario of 49.7 miles for mystery boxes in "Windham County." Windham County isn't even in Rhode Island--it's in neighboring Connecticut! But it's nestled right up along the Rhode Island border and the worst-case scenario for having to drive to find a Windham County letterbox is actually about 10 miles less than a worst-case scenario for having to drive to find a "somewhere in Rhode Island" letterbox.

So that's why you'll see Windham County mystery boxes show up before Rhode Island mystery boxes in the search results. In a worst-case scenario, they're probably closer--even if they are in a different state.

When it comes to figuring out the direction a mystery box is located, AQ can't be certain about the Providence County mysteries or the Rhode Island mysteries--we're inside of those locations and the mystery box could be in any direction from the city of Providence. However, the mystery boxes in Windham County, Connecticut--even without knowing precisely where it's located, AQ can tell that's it's "somewhere to the west" of Providence, and faithfully points in the correct direction of the mystery.

It's really pretty neat, and I hope it means more people will start looking for mystery boxes in their neck of the woods as a result. You don't have to do an area search to find mystery boxes--they're all around you, and that now shows up in the location-based searches. The more specific the mystery area is, the more likely you'll see it showing up in a location-based search.

For mystery boxes "somewhere in the United States" (for instance), you're better off just running an area search. AQ has a radius of 3,880.96 miles for the radius of the United States, so a location-based search would have to cast at least a distance of 3881 miles to include those, and tens of thousands of boxes would show up before it. Viewing mystery boxes in location-based searches generally works best if the mystery is a relatively small area such as states in New England or counties.

It's also possible to see mystery boxes show up in trip planner searches, but since a trip planner search is limited to a maximum of 30 miles off of the route being searched, you might not see them show up very often. Take this example of a search for all mystery boxes within 30 miles of I-95 between Key West and Portland, ME. Those county-wide mysteries in Providence County make the cut, along with a couple of mystery boxes in Norfolk County, MA, but that's it. (For the moment!) There might be other mystery boxes along the route, but AQ can't be certain that those other mysteries are within 30 miles of I-95.

If you've been adding custom locations and had to add a location that the geocoders couldn't find, you'll see a space for the "radius" of the location. This is the sort of thing it's used for, and it's very important the the number is approximately correct if you want the box to show up as expected in location-based searches and trip planner searches. You don't need to be exact--and since counties are never perfect circles (so far as I know)--it's impossible to be exact.

In fact, how AQ handles these calculations, it treats mystery boxes exactly like it does for non-mystery boxes. Every location AQ knows about has an associated radius, and it's added to calculated distance to create the distances you see listed in the search results. If you hide a letterbox in a large city park--take New York City's Central Park, for instance--the park has an average radius of 1.68 miles. If you run a search for boxes using Central Park as your search point, all Central Park boxes will show up as being 1.68 miles away. (Radius + calculated distance = final distance, i.e. 1.68 + 0 = 1.68) If you're standing in the center of Central Park, AQ believes those boxes might be up to 1.68 miles away from where you're standing. A box at a rest area with a radius of 0.1 miles--yep--AQ will add 0.1 miles to the calculated distance for that box in the searches.

The point is--whenever you see AQ list the distance, that's essentially a worst-case scenario for how far you'll have to travel to get the box.

On the trip planner, I'll also note, the radius of the location is actually added to the "offpath" distance--not the "mile marker" distance. The offpath column displays the worst-case scenario for how far off path you might have to travel to get the box. There's not really any "worst case mile markers." The box might be located somewhere between "MM10 and MM20" (if the radius of the location is 5 miles), but it's not really practical to list the same box for every MM that it might apply to. So in that case, the MM is based on the center point of the mystery location and the radius is applied to the offpath distance.

Clear as mud? =)

Back to those mystery boxes near Providence. From there, click through to the Map Results link. You'll notice the map is filled with red and green markers. The green ones are new and were added to accommodate all those mystery boxes out there.

The blue icons aren't on this map because we only searched for mystery boxes and the blue icons are used to denote "exact" locations. The red icons represented those boxes where people specified a city for the box but failed to provide an exact address. These boxes typically weren't mysteries, but the accuracy of their locations was always in doubt. And with the additional of genuine mysteries, the coordinates could be a long way off from the actual box location. A mystery box "somewhere in the United States" covers a lot of territory, and I thought it was prudent to be able to identify which boxes might be way off base.

If you've been paying attention so far, you might be wondering, "Yeah, okay, then why are there any red markers at all? All of the boxes in the search are mystery boxes! Shouldn't all of the markers be blue?"

And that's an excellent question. The thing with mystery boxes is that the line that used to identify what counts as a mystery and what does not count as a mystery has grown a little nebulous. Clark County, Georgia, for instance, has a radius of 10.31 miles while the city of Seattle has a radius of 16.59 miles. A box listed as "Clark County, GA" is almost certainly a mystery box, but a box in "Seattle, WA" probably is not--but the confidence level AQ has for the box in Clark County is actually better than it is for the city of Seattle.

It actually gets worse than that in a sense, but it doesn't show up on this particular map. Even a search for just mystery boxes can return a box with an "exact" location. How is that even possible? Because you might have solved the mystery and attached a custom location to the letterbox. Just because you solved the mystery and know where it is doesn't mean the box is no longer considered a mystery box! So if you used a bunch of custom locations, it's entirely possible that AQ will plot an exact location for a mystery letterbox, and use a blue marker as a result.

I haven't solved any of those mystery boxes in Rhode Island, Connecticut, or Massachusetts so AQ doesn't use any blue markers on my map of mystery boxes for the area, but if you have--you'll see them too!

See what a problem adding support for counties caused? Strange paradoxes like these... So now--when you add or edit a letterbox, you can set a "city-wide mystery box" or a "I'm only going to list the city, but this is not a mystery box" option. If you specify a location with a radius that's less than one mile, AQ will not allow it to be a mystery. That's narrowed down so much that for all intents and purposes, it doesn't seem fair to call it a mystery. And if you specify a location that has no name, no address, and no city listed--meaning it's a county-wide (or larger) area, it must be a mystery box and will set the mystery icon. If it's smaller than a county and larger than one mile, however, you'll now have the option to use or not use the mystery box icon on the box.

Don't worry about remembering these details--the only reason I mention all this is to explain part of the reason why AQ's concept of a mystery box is a bit more nebulous than before. Where a non-mystery box ends and a mystery box begins is a fuzzy line.

So when I got to the point where I had to update the map, I considered several options, and finally decided that the color the icon should reflect the relative "confidence level" AQ has about the box being near that specific point. If AQ believes the coordinates are within one mile of the actual box location, it uses a blue  marker. If AQ believes that the coordinates are within 30 miles of the actual box location, a red marker. And if AQ believes that the coordinates might be more than 30 miles away from the actual location of the box, it'll use a green marker. The markers plot the exact latitude and longitude coordinates of the specified location, and the color of the marker identifies how close the actual location of the box might be.

So even though every box in my search returned mystery boxes, some mystery boxes are known to be within a 30 miles radius (the county-wide mysteries if the county has a radius of less than 30 miles) and some mystery boxes are outside of that limit (the state-wide mysteries and county-wide mysteries if the county has a radius larger than 30 miles).

Looking at this map AQ generated, it would appear that most counties in Rhode Island and Connecticut are smaller than 30 miles and most counties in Massachusetts are larger than 30 miles in radius.

I should also point out--I got an e-mail from Kirbert who noticed that a search for mystery boxes in Florida plotted a point far out in the Gulf of Mexico as the "center" of Florida, who strangely saw nothing wrong with this--just that it was an interesting observation. =)

And he's right--this is actually normal and perfectly acceptable. Given the unusual shape of Florida's long panhandle and peninsula, the geocoders have figured out that the best single "point" to mark the center of Florida is actually in the Gulf of Mexico. Take a close look at the image I captured--it contains the entire state of Florida, and that green "A" marker is actually near the center of the image. So if you see mystery boxes mapped in watery locales such as this--just remember, that's not where the box is located--that's just the center point of the mystery area where the box can be found. It would, however, be troubling to see a blue marker at this location since a blue marker means that the box would be within one mile of the marker, and there's no land within one mile of the center point for Florida! A green marker? Nooo problem! =)

Like I said before, this update has a lot of new stuff packed into it, and it'll take awhile for me to try to explain it thoroughly and how all of these moving pieces work. =) That's enough for today, though. More tomorrow! =)

Road Trip!!!!!

Going on a road trip soon? If so, you might appreciate some of the upgrades the Trip Planner got with that Big Update a couple of nights ago. =)

I didn't really want to muck around with the trip planner, but alas, the lengthy tentacles that grew out of custom locations reached out and affected all sorts of subsystems along the way, and those changes effectively thrashed the trip planner to pieces. After all was said and done, the trip planner didn't work. Not even close. It was beyond help--it either needed to be replaced or retired. But the trip planner as we knew it was finished.

Amanda and I held a private ceremony to celebrate its demise--that trip planner had problems and often times I thought the results it returned were almost worse than worthless. I certainly wouldn't miss it, but I knew a lot of people on Atlas Quest would. No, I couldn't retire the trip planner permanently. No, I needed to create a replacement.

Of course, when building a replacement, I put some thought into what I should do differently for Trip Planner 2.0 and fix those pesky issues that plagued Trip Planner 1.0.

The first thing that needed fixing was a no brainer: The distances off-path from the route were highly inaccurate because distances were measured from the city center that the box was in--not the actual location of the letterbox. When I first created the trip planner, way back in 2004, Atlas Quest did not support addresses at all. It supported cities and only cities, and the trip planner was therefore designed to work with cities and only cities. I never upgraded the trip planner to work with addresses when the addressing feature came along.

Now that a complete replacement of the trip planner was necessary, I needed to fix this problem.

I also had another idea for the trip planner which I thought would be useful--a list of how far along the route that the letterboxes were located. If you run a search for all boxes on I-5 between Sacramento and Seattle, it would be nice to know that the next box in the list is 1.3 miles beyond the one you just found. In fact, wouldn't it be cool if, when you left Sacramento, you could reset the trip odometer to 0 and watch the numbers click off right where the boxes would be along the route? I was certain I could implement something to that effect, and by golly, I was going to try.

And finally, due to technical reasons I won't bore you with, there was a very limited number of large cities that the trip planner allowed you to use as starting and ending points along the route. I wanted to fix that so you could search between almost any two locations along a route.

Again, I toiled for weeks, rebuilding the trip planner from scratch. And finally, I finished, and I was immensely pleased with my work. =)

Let's admire it, shall we? Take these search results of all boxes located within 5 miles of I-5 between Sacramento and Seattle. The most obvious change is that the results have a new column: distance. The first box is just 0.2 miles out of Sacramento, and as you scroll down the list, you'll see the distance get larger and larger until you mile marker 730.1 in Seattle. (You'll have to change to the last page of the search results to see the Seattle boxes.)

This, I think, is very cool. Maybe not earth shattering, but still, very cool. =)

Now, if you examine the list closely, you'll notice that a lot of Sacramento boxes aren't in it. In fact, a lot of boxes from all of the large cities that I-5 goes through aren't in it. I mentioned yesterday that the geocoders now return information to me about the size of a location, and in Sacramento's case, it tells AQ that Sacramento has a radius of approximately 11.43 miles. So AQ thinks, "Hmm.... Any box listed as being somewhere in the city of Sacramento might be as far as 11.43 miles off of I-5, and this person only wants to see boxes that are known to be within 5 miles of I-5. Therefore, I better not display these boxes."

Weed, CA, however, is a much smaller town, and the geocoders report that it's only 2.8 miles wide. Therefore, AQ thinks, "Hmmm... Any box listed as being somewhere in the town of Weed is a maximum of 2.8 miles away. I may not know where in Weed this letterbox is located, but it doesn't matter--I know it's less than 5 miles away, so I'll display these boxes."

Additionally, distances are now calculated based on the known address of the location--not simply the city center, so calculated distances will be much more accurate. (Unless, of course, the letterbox has no address listed, at which point it'll use the city center for lack of a better reference point.)

In a nutshell, the distances off path will be much more accurate than ever before. In fact, they're so accurate, you might very well spot inaccuracies in the route.

When I originally created the trip planner, I pulled up maps and plotted the route one city at a time along its entire length. It was tedious and slow, and knowing that distances would only be as accurate as the city center, I took shortcuts. When the road had a series of sharp switchbacks, I plotted a straight line directly through it. If the route I plotted was off the actual route by a mile, no big deal--my shortcuts would be hidden in the calculations for city centers. (This is also why you might notice that Google Maps calculates the distance of I-5 from Sacramento to Seattle as 753 miles while AQ calculates 730 miles--skip a switchback or turn here and there, and it starts to add up!)

Fast forward to today--and now that calculated distances are much more accurate, my shortcuts from before have caught up with me. Discrepancies in the actual distances vs calculated distances will likely be due to my sloppy route plotting. I need to replot every route that AQ supports, but that could take months of effort, and I didn't feel it was necessary to hold up the update for this to be completed. It will happen, eventually, but in the meantime, the calculated distances are much better than before already--my plotted routes rarely went more than a mile away from the actual route while the city-centered calculations were often off by ten miles or more.

So there's still room for improvement in the off-path distances, and the trip planner still needs some work. The code that runs it is fantastic! The data that went into it--not so fantastic, and you should be aware of those limitations.

Now--a little about how to run a trip planner search. On the Simple Search page, it looks much like it did before: You select a route, then the starting point, then the ending point. The options for starting and ending points, however, are much more extensive than before. You'll see all the large cities like before, but a lot of the smaller towns the route travels through. The I-5 corridor has a whopping 97 towns to select from! That's about the only new thing to note there, though.

Running a trip planner search from the Advanced Search page is a bit more of a challenge. You won't find a "trip planner" a search type option anymore--it's all done through that "Location" box. To run a a trip planner search, you type in a location like this:

ALONG i-5 FROM sacramento, ca TO seattle, wa

The words ALONG, FROM, and TO are keywords that help AQ divide the text into pieces it can understand, and you can use pretty much anything as a location. Cities are the most obvious, but you could search from a specific address within a city, or a zip code, or a geographical feature, etc. Also, you don't have to fussy about the order you use the keywords. Equal to the above statement, any of these would also work:

ALONG i-5 TO seattle, wa FROM sacramento, ca

TO seattle, wa FROM sacramento, ca ALONG i-5

TO seattle, wa ALONG i-5 FROM sacramento, ca

FROM sacramento, ca TO seattle, wa ALONG i-5

I'll also mention that the first keyword is actually optional, and the following searches are exactly the same as the four above as far as AQ is concerned:

i-5 TO seattle, wa FROM sacramento, ca

seattle, wa FROM sacramento, ca ALONG i-5

seattle, wa ALONG i-5 FROM sacramento, ca

sacramento, ca TO seattle, wa ALONG i-5

I've put the keywords in all caps just so they stand out, but that's not required. Lowercase keywords work just as well.

Now, let's say you try running a trip planner search that looks like this:

ALONG i-5 FROM boston, ma TO seattle, wa

See the problem? I-5 doesn't run between Boston and Seattle. AQ is smart enough to figure this out (which is kind of surprising, really, because AQ really isn't very smart at all). But rather than give you an error, it tries to fulfill your request the best that it can and turns your search into a linear search. It runs a straight line search from Boston to Seattle. If this is sufficient for you purposes, great. If not... well, you'll need to adjust your search and try again. =)

Using the trip planner on the Advanced Search page is a bit more complicated than before, but it's the ultimate in power allowing you to specify a start and end point anywhere along a route. If you can't remember how to run the search, there's help a click away by clicking the help button by the location. Or, alternatively, you can use the simple search page to run the search, then edit the search if you want to tweak the results more than the simple page would allow you to do directly.

And finally, you can use a trip planner wherever you see this location option in a search--including event searches!  So, for instance, you can search for all events within 30 miles of I-5 between Sacramento and Seattle. A neat little perk. The output of the results isn't as cool as with letterboxes--there's not a special column for distances or distance off path of the events since I figured when an event takes place is more important than how far it is between two events on different dates. I doubt this feature will be used often, but it's there if you ever need it! =)

And.... I think that covers all that's new with the trip planner. It's bigger and better than ever before! And I'm not even done updating it. ;o)

Counties? They really do exist!

Please, don't play with the broken glass.....

Today's serial installment about the Great Update I did last night will be about counties. When I first created Atlas Quest, I made an enormous blunder: I didn't include information about counties with each location. I chose not to do this because it seemed like a quaintly American thing and I was trying to create a website that could support locations from around the globe--most of which has no concept of counties. And anyhow, who cares about counties? I was more concerned about cities. That, and the state it was in, was enough to narrow down the correct city, right?

Wrong.... way wrong. Turns out, there are huge number of small podunks and small towns or even parts of towns that have the same name in the same state, and it wasn't long before the first reports of towns being in the "incorrect" location started coming in. However, they were typically small enough that I would manually change the location to the "correct" place and just not support the town in the "wrong" place. It's not an ideal solution--only admins could move towns, so if you found this problem, you had to go through us. And, more often than not, people didn't even realize that boxes they listed sometimes ended up mapping to the wrong part of a state.

Additionally, especially for people who live in large states, it would have been handy to be able to list a mystery box as being "somewhere in XYZ county" instead of "somewhere in ABC state." For a small state such as Rhode Island where any mystery box in the state is practically walking distance, not a big deal. For a large state such as California or Texas, a mystery box on the completely other side of the state may be a no-go.

And because of this massive design flaw introduced before AQ even opened for business, both of these problems lingered.

About a year after AQ went live, I tried to fix this problem after the fact. I worked on it for a couple of weeks, trying to fit counties between cities and states, and it was frustrating. And finally, it collapsed in a heap of failure. The way the database was structured, I just couldn't make it work, and I wasn't willing to commit to significant changes in the database to make it work--that probably would have taken me months to implement--assuming it even worked in the first place. I failed. Atlas Quest hobbled along, blissfully ignorant about counties.

Then I decided to support custom locations on boxes. Early on, while investigating certain aspects of what I'd need to implement, I noticed a problem with the geocoder AQ was using. (A geocoder, for those not familiar with technical terms, is a system that can translate an address into latitudue and longitude coordinates--critical for AQ to accurately map locations.) The geocoder AQ was using had been deprecated. Which means that it worked--for now, but Google might stop support of it at any time and that would leave AQ high and dry. I needed to replace the geocoder, ASAP.

That first geocoder I used was a huge learning experience for me, and if I had to rebuild a new geocoder, I could certainly do a much better job of it than my time around. The biggest issue was being overly reliant on just one external geocoder. What if Google suddenly stopped supporting the one I used? What if they changed their rules, or started charging for access beyond what I could afford? What I really needed was support for several geocoders--a minimum of two external geocoders, but the more the better. If one geocoder couldn't figure out the location you were trying to use, maybe a different one would? I could chain multiple geocoders together for a "super geocoder" capable of encoding locations that neither of them alone could do.

At this point, I was going slightly astray from my main goal of custom locations on boxes, but custom locations are only as good as the geocoders they are built from, and I was determined to make sure the new one would be awesome compared to the geocoder of the past.

When I looked at the geocoder Yahoo makes available, I found it included a piece of information I never had before: the radius of the location. For the first time, I had a source of information about the size of a location. There's a big difference between the size of a city such as Seattle and the size of a state such as California, and I immediately knew I could make very good use of such information to generate better search results.

And as they say, in for a penny, in for a pound. I was already going to completely rewrite the geocoders, I may as well start recording information about the size of the locations and the county that locations are in. Let's do this RIGHT! =)

It was time to take another whack at solving the "county problem." (Among others, but this blog entry will focus on the counties.) I toiled away for weeks, creating several geocoders, chaining them together, and associating counties with locations and storing information about the size of each location. And finally, I was done. It was working.

And now AQ supports counties.

When you list a new letterbox, you'll usually type in the city and state for your location, and most of the time, AQ will correctly figure out the county. If, however, you notice that the box seems to map to the wrong part of the state, edit your box and check the location. AQ will display what county it's using for your location, and if it's incorrect, you can fix it.

Additionally, you can now list mystery boxes that are "somewhere in XYZ county." For instance, you could list a mystery box as being in "King County, WA" or "Washington County, OR."

I noticed a lot of people added this information as the "address" of their mystery box, and I had AQ go through and automatically convert them into county-wide mystery boxes. It might not be a bad idea to double check the locations of the mystery boxes you planted to make sure AQ got this right. If you were clear and only wrote something like "King County" or "Washington County," there shouldn't have been trouble for the geocoders. If you tried typing something like "King or Pierce County," typed the name of the county incorrectly, or something like "Eastern King County"--something less than completely straight-forward, the geocoder was much more likely to choke on it and do something you may not have wanted.

Now a little about how to search for county-wide mystery boxes. If you visit the Advanced Search page, you won't find "Area Search" as a search type option anymore. The reason is simple: It's not needed anymore. To search for boxes in a county, just type the county name. King County, WA, for instance. This returns all boxes within the county--mysteries or otherwise. What if you just want the mystery boxes in King County? Before clicking that search button, click the "Mystery Boxes" attribute first to get this list.

When you run an area search like this, the "distance" option is ignored. All boxes are within the boundaries of King County. (As an aside, if you set the "distance" to zero, you can run an area search for all boxes within a city or even a specific park within a city. It forces all searches into becoming an area search.)

Now let's head on over to the Simple Searches page. I wanted to keep a simple version of an area search available, and you'll find that "state" part of an area search has been renamed into "region." If you look at the drop-down list, you'll see why--it includes all of the states and counties that you can run an area search for from the selected country. Before you go rushing off to run a search for your county, I should point out that the list does not include every county in the United States--it only includes counties if there's at least one letterbox listed as being within that county. For counties that have no boxes in them, you won't see them in the drop-down list. And that's okay--there's nothing to search for there anyhow. =) As soon as someone adds a box to the county (mystery or not, it doesn't matter), the county will start showing.

I also made another slight improvement that almost nobody will notice--but if you live outside of the United States, you'll love this one. =) When you open the Simple Search page, AQ defaults the country to the one you have listed in your profile. If you live in Canada, the area search will default to Canada. If you live in New Zealand, the area search will default to New Zealand. However, the only place AQ tracks your location is from what you type in your profile, so you'll need to fill out the location on your profile for this to work. (You don't even have to specify a specific city, county, or state--just listing the country is enough to make it work.)

So that's your lesson for today. =) Tomorrow, I'll be back with more details about the Big Update.

Three Months in the Making!

Vrrrooooommmm!!!!!! Look ma, no hands!

The day the solution hit me was April 10th. I know this, because I was absolutely giddy when I thought of it, and I posted about it to the AQ Webmasters board so Wassa could bask in my brilliance. =) For years people have wanted to be able to add their own location information to boxes that could be used in their searches. So, for instance, if you solved a mystery box, you could mark the actual location and subsequent searches would return the box in that location. (Just for that person, though--not for everyone, of course!)

I love that idea--I've wanted to run with that idea for years but kept running into technical issues that stopped me cold. I just couldn't figure out how to keep the database queries running fast and efficient with such an option.

I got to thinking about the problem again after reading that Aiphid's Box Radar app let people do this. I'll admit--it was a little annoying. Here I've been suffering from this problem for years without a solution, and some young whipper-snapper comes along and does exactly that in all about a week with an Android app. That darned app has more functionality than Atlas Quest! Kudos to him, but still.... I was jealous.

I haven't seen the code for Box Radar, but I could imagine how it would work if I created it, and it would have been easy. Seems so unfair than a feature can be so easy for an app and so difficult for a website. But admittedly, the app only had to download a small subset of all boxes--probably less than a thousand--while Atlas Quest supported over 100,000 listings. And the data stored in an app can be changed without worrying about how it might affect others. He could overwrite the location data and not worry about someone else coming along and seeing it. It's not like someone else will come along in ten seconds and run the same search on the owner's Droid.

So I stewed in misery, unable to figure out how to implement something that, on the surface, seems so utterly simple.

Then I decided I needed to do something about it, and I implemented a page that allowed me to set a location for a letterbox and store it in the database. And when I pulled up the box listing, it would show the original location along with my own changes (if there were any). It was pretty, but completely and totally worthless because that information was never used in the searches. I couldn't figure out how to integrate it into the search results efficiently. Argh! For all the functionality it added, I could have just typed in the location as a box note and accomplished the same thing.

So I did what I often do when I run into a problem without a solution--I went for a walk to think. =)

And during this walk, the solution hit me. Smacked me right across the side of the head and left me silly. I could totally make this work. It would require a relatively small change in the structure of the database, and a heap of changes to the code that rested on top of it, but I was absolutely certain I could make this work. It would be a huge effort, though. The change to the database, as I said, was relatively minor, but the changes required in the code would be extensive. If it took less than a month, I'd be surprised.

And when I got back home, I posted to the webmaster's board to tell Wassa about my idea, which is how I know the solution finally hit me on April 10th. =)

Letterbox searches are at the heart of Atlas Quest, and I started making a mental list of all parts this change would affect and the added difficulty of transitioning from the one type of a search to a new type of search. I wondered, since I was going in deep to muck around with the code, if I could fix a few other issues along the way. I wondered how I could test my changes before rolling it out on the live website. The kind of changes this would entail invariably would break lots of stuff, and I worried what I'd do if it broke so badly I couldn't get it fixed quickly but already passed the "point of no return."

So I started taking baby steps. Early on, I discovered that the geocoder I was using had been depreciated and had to be replaced. Well, I thought, I could certainly make a few improvements to that! I spent weeks on it, creating multiple geocoders which I've talked about before. Then I connected them to profile locations--a low risk way to test the geocoders and fix any glitches with them.

Then I expanded it to blog searches--which had always been dreadful anyhow. I didn't put much effort into that in the past because I didn't really expect many people would use it, but now I could fix all those problems while testing the changes I would later introduce to boxes.

Then it expanded to virtuals, which had additional requirements and was the first solid test for how box searches would look and how they would work. Virtuals were easy, though--none of them ever had location information, so I didn't have to worry about making sure old code continued to work--just that the new code worked as expected.

Then it expanded into event listings, which was a little more challenging since it needed to work with older code. And all along the way, each feature touched by these changes improved, often times so quiet that nobody noticed. =)

And then finally, it was time to roll out the changes to letterboxes. The very heart of Atlas Quest. The new code I created seemed pretty solid and was designed to be very easy for me to reuse across the website, and--for the most part--I didn't expect any major issues rolling out the feature to boxes. There was still a lot of work to integrate the changes into Atlas Quest, but it would be manageable.

Yes, Wassa Jr., I too think it's time
for a break. Let's go hiking! =)

And, at long last, the feature I wanted to support, the feature I've been working towards for three months, is finally here: The ability to set a private location for a letterbox--a location that will be used instead of whatever the owner of the box listed whenever you run a letterbox search.

This feature has taken me three months to fully implement. Seems like a relatively easy, straight-forward feature, doesn't it? Okay, admittedly, I improved a few other things that this feature touched along the way, but for the last three months, this is the one I've been shooting for.

It was an enormous undertaking, and that's partly why I've decided to make it a premium member only feature for the time being. It's premium members that have supported me and allowed me to work for three months to get this feature implemented, and if I had been forced into a regular 9-to-5 job, I'd never have had the time or energy to implement it at all. This really is a feature that could only have happened because of support from premium members, so--for now, at least--this will be a premium member perk. Thank you, premium members, for your support. I couldn't have done it without you. =)

Now--let's get into the guts of the feature. When you view the box details page, you'll see the "Location" like you always have. Premium members will also see a "Custom Location" listed immediately below it. So even if you set a custom location, you can still see what the owner of the box originally had listed as the location.

Since no boxes will have a custom location until you add one, it'll say "None specified" along with a small icon of a pencil that allows you to set a custom location. Click that and follow the prompts to add a custom location to the box. Save the location, and you're done.

Now, all letterbox searches you run will use your custom location instead of the original location. The location shown on the search results page will be your custom location--not the original location used for the box. The only places you'll see the original location is on the box details page and the clue page, right next to the custom location you entered.

As always, with an update this big, there are bound to be bugs, so if something doesn't seem to work correctly, give me time to fix it. =)

Let me also note that there are several additional noteworthy changes with this update, but if I discussed them all in this post, you're head would probably explode. =) So.... I'm going to post about some of the other changes over the next few days rather than one enormously massive post that will make your head explode. If you see a change I haven't mentioned yet, be patient. You'll probably see me blog about it at some point over the next few days where I'll explain it in more detail.

Happy trails!