Skip to main content
The Locations API allows you to search for geographic locations used in the RC system. Locations are used to filter profiles and represent where Recursers are based.

​
Location Struct

The Location struct represents a geographic location:
src/rc_api.rs:37-47
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Location {
    pub id: u32,
    pub name: String,
    #[serde(default)]
    pub short_name: Option<String>,
    #[serde(rename = "type", default)]
    pub location_type: Option<String>,
    #[serde(default)]
    pub ascii_name: Option<String>,
}
​
Location
struct
Geographic location information.

​
Search Locations

Search for locations by query string.
src/rc_api.rs:542-559
/// Search for locations
pub fn search_locations(&self, params: LocationSearchParams) -> Result<Vec<Location>> {
    let url = self.build_url("/locations");
    let mut query_params = vec![("query", params.query)];
    
    if let Some(limit) = params.limit {
        query_params.push(("limit", limit.to_string()));
    }
    
    let response = self
        .client
        .get(&url)
        .headers(self.auth_headers())
        .query(&query_params)
        .send()?;
    
    Self::handle_response(response)
}

​
LocationSearchParams

src/rc_api.rs:329-333
#[derive(Debug, Default, Clone)]
pub struct LocationSearchParams {
    pub query: String,
    pub limit: Option<u32>,
}
​
search_locations
fn(&self, LocationSearchParams) -> Result<Vec<Location>>
Search for locations matching the query.Parameters:Returns: Result<Vec<Location>>API Endpoint: GET /api/v1/locations?query={query}&limit={limit}

​
Examples

use rc_api::{RcApiClient, LocationSearchParams};

let client = RcApiClient::new(token)?;

let locations = client.search_locations(LocationSearchParams {
    query: "New York".to_string(),
    limit: Some(10),
})?;

for location in locations {
    println!(
        "ID: {}, Name: {}, Type: {:?}",
        location.id,
        location.name,
        location.location_type
    );
}

​
Using Locations with Profiles

Locations can be used to filter profile searches: 
use rc_api::{LocationSearchParams, ProfileSearchParams};

// First, find the location ID
let locations = client.search_locations(LocationSearchParams {
    query: "Brooklyn".to_string(),
    limit: Some(1),
})?;

if let Some(brooklyn) = locations.first() {
    // Then search for profiles in that location
    let profiles = client.search_profiles(ProfileSearchParams {
        location_id: Some(brooklyn.id),
        ..Default::default()
    })?;
    
    println!("Found {} Recursers in Brooklyn", profiles.len());
}

​
Location in Profiles

Profiles include a current_location field: 
let profile = client.get_profile_by_id(12345)?;

if let Some(location) = &profile.current_location {
    println!("{} is currently in {}", profile.name, location.name);
    
    if let Some(short_name) = &location.short_name {
        println!("Short name: {}", short_name);
    }
}

​
Common Use Cases

​
Find All Locations in a Region

let locations = client.search_locations(LocationSearchParams {
    query: "California".to_string(),
    limit: None,
})?;

println!("California locations:");
for location in locations {
    println!("  - {} (ID: {})", location.name, location.id);
}

​
Build a Location Selector

fn get_location_id(client: &RcApiClient, query: &str) -> Option<u32> {
    let locations = client.search_locations(LocationSearchParams {
        query: query.to_string(),
        limit: Some(5),
    }).ok()?;
    
    if locations.is_empty() {
        println!("No locations found for: {}", query);
        return None;
    }
    
    println!("Select a location:");
    for (i, loc) in locations.iter().enumerate() {
        println!("  {}. {} (ID: {})", i + 1, loc.name, loc.id);
    }
    
    // In a real app, you'd prompt the user to select
    Some(locations[0].id)
}

​
Filter Profiles by Multiple Locations

let cities = vec!["New York", "San Francisco", "London"];
let mut all_profiles = Vec::new();

for city in cities {
    let locations = client.search_locations(LocationSearchParams {
        query: city.to_string(),
        limit: Some(1),
    })?;
    
    if let Some(location) = locations.first() {
        let profiles = client.search_profiles(ProfileSearchParams {
            location_id: Some(location.id),
            ..Default::default()
        })?;
        
        all_profiles.extend(profiles);
    }
}

println!("Total profiles across all cities: {}", all_profiles.len());

​
Location Search Tips

The location search is flexible and searches across multiple fields including full names, short names, and ASCII names.

​
Search Strategies

  • Specific cities: “Brooklyn”, “San Francisco”, “London”
  • States/Provinces: “California”, “Ontario”, “New South Wales”
  • Countries: “United States”, “Germany”, “Japan”
  • Partial matches: “San” might return “San Francisco”, “San Diego”, etc.

​
Handling Results

let locations = client.search_locations(LocationSearchParams {
    query: "San".to_string(),
    limit: Some(20),
})?;

if locations.is_empty() {
    println!("No locations found");
} else if locations.len() == 1 {
    println!("Found exact match: {}", locations[0].name);
} else {
    println!("Found {} possible matches:", locations.len());
    for loc in &locations[..locations.len().min(5)] {
        println!("  - {}", loc.name);
    }
}

​
Next Steps

Profiles

Use location filters in profile searches

Batches

Work with batch data

Error Handling

Handle location search errors

Build docs developers (and LLMs) love

Get started for freeTalk to us