Handling City Filter Uploads
By the end a partner can post a CSV or XLSX of locations to your API, and only the rows inside your city or radius reach storage. The rest are counted and reported, never dropped silently.
1. The endpoint takes the file and parses it into rows
on_startup_register_uri_file (on api file upload) with URI locations/upload registers a POST endpoint for multipart/form-data. Its handler function gets the upload on a file pin, ready for the file blocks. Parse it into an array of row objects:
file_parse_csv(parse CSV) detects the separator, reads headers, and outputs one object per row. Itserrorpin catches files that are not CSV at all.file_parse_xlsx_to_array(parse XLS/X to array) does the same for the first worksheet of an Excel upload.file_parse_xlsx(parse XLS/X) gives you the whole workbook as an object.
Only accepting the file for later? file_move (move) takes it out of the temp directory instead of parsing it in the request.
2. Two blocks decide whether a row is inside your area
An uploaded file becomes rows: get takes the file from the form, parse CSV turns it into an array of objects, and filter by geo distance keeps only the rows whose location lies within their own radius of from city (here Breda). array length counts what survived.
The canvas starts with function_get_file_from_form, which reads a file from a form on a state page. On an upload endpoint, your handler's file pin takes its place. Everything after it is the same:
geo_point_from_city(from city) resolves the target city to its centre point. A city name is not unique within a country, so wirecountry_code, andprovincewhen you know it.array_filter_geo_distance(filter by geo distance) keeps the rows whose own location field lies within reach.location_keynames the field holding the row's geo point,distance_keythe field holding its radius. Rows carry their own reach, so a single pass handles "within 5 km" for one row and "within 500 m" for the next.- What does not match comes out on
out_of_range, so you can report or log the rejects instead of dropping them silently. If the block's configuration is wrong it fails closed: every row lands there.
| Your rows have | Use |
|---|---|
| Plain lat/lng numbers instead of a geo point | Convert first with geo_point_lat_lng_to_point (create). |
| One fixed radius for every row | Test each row's point with condition_geo_is_point_in_circle (point in radius) inside an iterator. |
| Documents already in storage | Filter at the storage level with query_bool_geo_distance (distance), so documents outside the area are never read at all. |
3. Validate, enrich and store what survived
Validate
Check each row's point with
geo_point_validate(is valid). Uploads regularly contain empty or swapped coordinates, and one bad row should not poison the batch.Enrich
geo_point_reverse_geocode(reverse geocode) resolves the point to street, city, province and country. Writing those onto the document withmutations_set_bp_field_multiple(set fields) makes the rows searchable by city name later, a combination production blueprints use directly on the upload path.Store
Write the batch with
function_upsert_document_from_mutations(upsert document) inside afunction_foreach(foreach) loop, with aguid_seedbuilt from the row's own identifier: re-uploading the same file then updates rows instead of duplicating them.Reply
Send a small summary object: rows received, kept, rejected. Build it with
object_new_fields(new object) fed byarray_length(length) on both output arrays, and send it withhttpconnection_set_json(reply in JSON), the response backbone from Common Blueprint Patterns.
curl -X POST "https://<cluster-url>/api/v1/locations/upload" \
-H "Authorization: Bearer <access_token>" \
-F "file=@locations.csv"Notes from practice
- Large files do not belong in the request: parse, reply 202, and filter and store through
function_custom_execute_from_queue(execute in queue). See Queue. - The geo blocks are offline lookups, so filtering ten thousand rows costs no external calls and no meaningful time.
- Scope the endpoint and rate limit it; an open upload endpoint is an invitation. The block has
rate_limitpins, and itsfilesizepin defaults to 5 MB. See Remote Access Control. - Branch on the parse block's
erroroutput before touching the array: replying 400 with "not a CSV" beats storing nothing and replying 200.
Next steps
Places and Geo Search The offline dataset behind the geo filter blocks, and the search blocks built on it. File Upload & Processing Web pages, assets and background pipelines for uploads in general. Common Blueprint Patterns The response backbone and error-handling shapes used here.Frequently asked
How do I accept a CSV upload through a RUAL API?
Take the file off the multipart form with function_get_file_from_form, then parse it with file_parse_csv into an array of row objects. The parse block detects the separator and reports files that are not CSV on its error pin.
How do I keep only uploaded rows inside a city in RUAL?
Resolve the city with geo_point_from_city and filter the parsed rows with array_filter_geo_distance, which reads each row's location and allowed radius from fields you name. Rows that fall outside come out on the out_of_range pin, and all of it runs offline against datasets on the node.
