Skip to content
locations / 1

The options endpoint

Last updated:

On this page

Route::locationOptions() registers a read-only JSON endpoint per type. It's what the cascading selects load their options from, in the format javaabu/forms' and @javaabu/forms' select2 request.

Route::middleware('web')->group(function () {
    Route::locationOptions();
});
URL Name
GET /location-options/countries location-options.countries
GET /location-options/states location-options.states
GET /location-options/cities location-options.cities
GET /location-options/atolls location-options.atolls
GET /location-options/islands location-options.islands
Option Default Description
prefix location-options The URL prefix
middleware [] More middleware, e.g. ['auth'] or ['throttle:60,1']
controller config('locations.controllers.options') The controller

The route names come from config('locations.options_route'), and the selects find the endpoint by them. To rename the routes, change the config, not the macro.

The endpoint is public by default: it only lists names and codes. If yours aren't public, put it behind middleware and give the same users the selects.

Requests

GET /location-options/islands?filter[atoll]=2&filter[search]=dhi&per_page=-1
Parameter Description
filter[search] Matches names, Dhivehi names and codes
filter[…] The type's filters (below)
per_page Options per page, up to 100 (default 20). -1 returns every match, up to config('locations.max_options')
page The page

Other parameters the select scripts send (fields, include, append) are ignored.

Filters

Type Filter Value
states country A country's id or alpha-2 code
cities country A country's id or alpha-2 code
cities state A state's id
atolls country A country's id or code: every atoll for the Maldives, none for any other
islands atoll An atoll's id or code (HA)
islands category A category, or several (filter[category][]=residential&filter[category][]=tourism)
islands inhabited 1 for residential islands only
islands named Named islands only. On by default, 0 includes unnamed features

Unknown filters are ignored.

Responses

With per_page=-1:

{
    "data": [
        { "id": 12, "name": "Dhidhdhoo", "code": "LD0568" },
        { "id": 15, "name": "Filladhoo", "code": "LD0993" }
    ]
}

Otherwise, a Laravel paginator, with next_page_url for the select's infinite scroll:

{
    "current_page": 1,
    "data": [{ "id": 12, "name": "Dhidhdhoo", "code": "LD0568" }],
    "next_page_url": "https://example.test/location-options/islands?page=2",
    "last_page": 3,
    "total": 52,
    "…": "…"
}

name is the option's label in the request's locale (optionLabel()): HA. Haa Alifu or ހއ. ހާ އަލިފު for atolls, the localized name for everything else. Use SetLocale-style middleware on the endpoint if your app switches locales per request.

Searching as the user types

For a long list (every island of the Maldives), use javaabu/forms' AJAX mode with the endpoint instead of loading everything:

<x-forms::select2
    name="island_id"
    :options="\Javaabu\Locations\Models\Island::query()"
    :ajax-url="route('location-options.islands')"
    is-ajax />
<Select2 name="island_id" label="ރަށް" isAjax ajaxUrl="/location-options/islands" />

In code

The filters are also available as a helper:

use Javaabu\Locations\Support\LocationOptions;

LocationOptions::filter('island', Island::query(), ['atoll' => 'HA', 'inhabited' => true])->get();
LocationOptions::url('island'); // https://example.test/location-options/islands, or null when not registered
Documentation
All packages

javaabu/locations

Source on GitHub