Locations

Search for geographic locations

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.

Show Fields

id · u32 · required

Unique identifier for the location

name · String · required

Location name (e.g., “New York, NY, USA”)

short_name · Option<String>

Abbreviated location name (e.g., “NYC”)

location_type · Option<String>

Type of location (e.g., “city”, “country”, “region”)

ascii_name · Option<String>

ASCII-only version of the location name

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:

Show LocationSearchParams

query · String · required

Search query string (searches location names)

limit · Option<u32>

Maximum number of results to return

Returns: Result<Vec<Location>>

API Endpoint: GET /api/v1/locations?query={query}&limit={limit}

Examples

Search by City

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