What Rayo Barcelone Actually Is
I ran into Rayo Barcelone a couple years back when a client needed batch geocoding done on a messy dataset of ~40,000 addresses across Southern Europe. The docs were sparse, the pricing page changed twice before I actually signed up, and the API response format shifted between v2 and v3 without much notice. So here's what I know from using it in production. Rayo Barcelone is a geocoding and reverse-geocoding API service based in Barcelona. It handles forward lookups (address to coordinates) and reverse lookups (coordinates to address), plus some POI search and autocomplete endpoints. It's not the biggest player — you've got Google, Mapbox, Nominatim, HERE — but it carved out a niche around coverage in Iberian countries and reasonable pricing at scale.
Rayo Barcelone Setup and First Request
Sign up, grab your API key from the dashboard, and you're basically ready to go. The base endpoint is standard REST, JSON responses, and you authenticate with a header. A basic forward geocode request looks like this: GET https://api.rayobarcelone.com/v3/geocode?address=Carrer%20de%20Bergara%208,%20Barcelona&key=YOUR_KEY Response gives you lat/lng, confidence score, matched components (street, number, city, postal code), and a type classification for the result. Simple enough.
The rate limit on the free tier is 100 requests per minute. If you go past that, you get a 429 and your call drops. I learned that the hard way running a 50,000-record import — started getting 429s about 90 seconds in. The workaround was pretty straightforward: batch the requests into chunks of 80, add a 750ms delay between batches using a simple async loop with asyncio.sleep, and you stay under the limit without throttling issues. Cuts a 45-minute job down to roughly 50 minutes, which is fine.
Get the Full Details
How It Compares to Alternatives
For Spanish and Portuguese addresses, Rayo Barcelone usually beats Nominatim on accuracy. Nominatim is free but its OpenStreetMap data has gaps in smaller municipalities, and it will politely refuse to geocode anything that looks like bulk usage. Rayo Barcelone charges per 1,000 requests but handles bulk without complaining. Google Maps Geocoding API is more accurate overall but dramatically more expensive once you scale past a few thousand lookups a day. Mapbox sits in the middle — good precision, decent pricing, weaker Iberian coverage than Rayo Barcelone in my testing. Here's the thing most people miss: Rayo Barcelone's confidence score is actually useful. A lot of geocoders just return results and let you figure out if they're garbage. Rayo Barcelone gives you a 0–100 confidence number per result, and the component breakdown lets you verify exactly what matched. When I was validating a logistics dataset, I filtered anything below 75 confidence and manually reviewed those. Cut my error rate from about 8% down to under 2%.
Pitfalls and Edge Cases
One thing that tripped me up: the autocomplete endpoint doesn't respect country codes the way you'd expect. If you send country=ES, it still returns results from Portugal and Andorra in the top hits sometimes. The fix is to post-filter by country in your response handler rather than relying on the API to do it for you. Another issue: batch geocoding via CSV upload on the dashboard has a 10,000-row limit per file. My dataset was 40,000 rows, so I split it into four files and queued them sequentially. Each file took about 3–4 minutes to process. Not slow, but the dashboard doesn't show progress per-file — just a single spinner that resets when the next file starts, which is confusing if you're watching it. The API v3 migration is worth noting. If you're reading old tutorials or Stack Overflow answers, they might reference v2 endpoints that return slightly different field names. Specifically, results[].geometry in v2 became results[].location in v3, and the formatted_address field changed structure. I spent about two hours debugging why my parser was returning None values before I noticed the version mismatch. Stick to the v3 docs and ignore everything else.
Pricing Reality
The free tier gives you 2,500 requests per month. After that, it's roughly $0.50 per 1,000 requests on the standard plan. Volume discounts kick in at 100,000+ requests/month, dropping the per-thousand rate to around $0.30. For comparison, Google charges about $7 per 1,000 at equivalent volume. Rayo Barcelone is genuinely cheap if your use case is primarily Iberian. The downside is that for addresses outside Spain, Portugal, Andorra, and parts of Latin America, accuracy drops noticeably. I tested it against known coordinates in Paris and Berlin and the confidence scores were 30–40% lower than the same addresses in Barcelona. If your dataset is global, you'd be better off using a multi-provider strategy — Rayo Barcelone for Iberian addresses, Mapbox or Google for everywhere else. I built a simple router that checks the country code from the address string and routes accordingly. Took about three hours to implement and cut my total geocoding cost by roughly 60%.
Bottom Line
Rayo Barcelone is solid if you're working with Spanish or Portuguese addresses and want something cheaper than Google without the limitations of Nominatim. It's not a general-purpose solution for every geography. The documentation is adequate but not exhaustive, the v2-to-v3 migration was messy, and the rate limits will bite you if you're not careful with bulk imports. For what it does well, though, it's reliable and affordable. Just stick to v3, throttle your requests, and filter by confidence score.
