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. Its error pin 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.

Studio canvas example for the parse CSV block: upload, parse, filter by city.

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 wire country_code, and province when you know it.
  • array_filter_geo_distance (filter by geo distance) keeps the rows whose own location field lies within reach. location_key names the field holding the row's geo point, distance_key the 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 haveUse
Plain lat/lng numbers instead of a geo pointConvert first with geo_point_lat_lng_to_point (create).
One fixed radius for every rowTest each row's point with condition_geo_is_point_in_circle (point in radius) inside an iterator.
Documents already in storageFilter 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

  1. 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.

  2. Enrich

    geo_point_reverse_geocode (reverse geocode) resolves the point to street, city, province and country. Writing those onto the document with mutations_set_bp_field_multiple (set fields) makes the rows searchable by city name later, a combination production blueprints use directly on the upload path.

  3. Store

    Write the batch with function_upsert_document_from_mutations (upsert document) inside a function_foreach (foreach) loop, with a guid_seed built from the row's own identifier: re-uploading the same file then updates rows instead of duplicating them.

  4. Reply

    Send a small summary object: rows received, kept, rejected. Build it with object_new_fields (new object) fed by array_length (length) on both output arrays, and send it with httpconnection_set_json (reply in JSON), the response backbone from Common Blueprint Patterns.

Try it
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_limit pins, and its filesize pin defaults to 5 MB. See Remote Access Control.
  • Branch on the parse block's error output 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.